Update docs for current upstream drift

CLAUDE.md

@@ -91,6 +91,11 @@ All documentation work follows `source audit -> draft -> verify`. Follow the det
 - Lead with the product, user task, or developer path, not with internal repo or implementation names, unless the tool name itself is the topic of the page
 - Do not surface provenance language such as `current-merged-truth`, "current merged", refs, audits, or verification modes in rendered prose. Keep that information in verification comments and workflow docs only.
 - Do not use repo names as primary page titles, nav labels, or opening framing unless the repo itself is the topic.
+- Avoid time-relative or changelog-style wording in rendered docs unless the page is explicitly comparing versions. Prefer direct statements of fact over words like `current`, `now`, `currently`, or phrases such as `in the current implementation`.
+- Use `path` language only on pages where the reader is explicitly choosing between routes. In normal prose, prefer phrases like "using the SDKs", "using the CLI", or "building in Rust with ant-core".
+- Prefer system behavior and user-facing tool names over repo names in ordinary explanatory prose.
+- Avoid provenance terms such as `upstream` and `downstream` in rendered prose unless the page is explicitly about source repositories, contribution workflow, or source verification.
+- Do not narrate the evidence in rendered prose. Avoid phrases like `the README says`, `the README notes`, `the README documents`, `the documentation describes`, `the relevant repos`, or `the sources covered here`. State the system, tool, or workflow directly and confidently. If a claim is not strong enough to state directly, re-audit it or remove it.
 - Expand important acronyms on first use when that helps a first-time reader.
 - See [Audience and objectives](#audience-and-objectives) for reader assumptions
 
@@ -109,6 +114,8 @@ Never use:
 
 All technical terms must match the terminology lockfile below exactly. Using the wrong form is a linting error.
 
+On first mention in rendered prose, expand important acronyms when that helps a first-time reader. For example, use `Autonomi Network Token (ANT)` on first mention, then `ANT` afterward.
+
 ### Code examples
 
 - Must be **complete and runnable**. Never snippets that require imagination.
@@ -124,10 +131,12 @@ All technical terms must match the terminology lockfile below exactly. Using the
 - Every page must be **self-contained**. No "as we discussed in the previous section" or "see above."
 - An agent reading any single page via llms.txt should understand the topic without needing other pages.
 - Link to related pages at the end, not inline as prerequisites.
-- Getting Started and How-to pages must explain what tool or path they cover, why you would choose it, and where the alternatives live when multiple supported paths exist.
+- Getting Started and How-to pages must explain what tool or route they cover, why you would choose it, and where the alternatives live when multiple supported routes exist.
 - Explain a tool or interface before telling the reader to install, run, or configure it.
 - Titles should describe user outcomes or choices, not internal mechanisms, unless the mechanism name itself is the thing the page teaches.
 - Do not use inline code spans in headings. For commands, endpoints, and signatures, use a readable heading and put the exact literal syntax on the next line.
+- Glossary entries should be short, timeless definitions. Avoid changelog phrasing, repo framing, and unnecessary implementation qualifiers.
+- Do not inline-link repo names throughout normal prose by default. When useful, add a short `Upstream sources` section near the end of overview, concept, or reference pages instead.
 
 ### Formatting
 
@@ -438,8 +447,8 @@ NAT traversal | NAT Traversal, nat traversal | Techniques for connecting peers b
 QUIC | quic | UDP-based transport protocol
 
 # Payments
-ANT token | Ant token, ant token | ERC-20 token on Arbitrum used for network payments
-Arbitrum | arbitrum | Layer 2 Ethereum network where ANT token operates
+Autonomi Network Token (ANT) | ANT token, Ant token, ant token | ERC-20 token on Arbitrum used for network payments
+Arbitrum | arbitrum | Layer 2 Ethereum network where Autonomi Network Token (ANT) operates
 pay-once | pay once, Pay Once | Storage payment model: single upfront payment, no ongoing fees
 Merkle batch payment | merkle batch payment, Merkle Batch Payment | Efficient multi-chunk payment verification using Merkle trees
 

docs/SUMMARY.md

@@ -10,7 +10,7 @@
 - [Build with the SDKs](getting-started/install.md)
 - [Your First Upload with the SDKs](getting-started/hello-world.md)
 - [Use the ant CLI](getting-started/using-ant-client.md)
-- [Build Directly in Rust](getting-started/build-directly-in-rust.md)
+- [Build in Rust with ant-core](getting-started/build-directly-in-rust.md)
 
 ## Core Concepts
 

docs/architecture/system-overview.md

@@ -10,29 +10,29 @@
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 727a75c46bebc6d5948ea7754debd4220ead9400
-  verified_date: 2026-04-02
+  source_commit: 796d0df75d748419a004aec6f5e288b41d8b496e
+  verified_date: 2026-04-04
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: ant-node
   source_ref: main
-  source_commit: 8e9541b5bd5ae9791a1b9d037c62c76ff8a7d0c8
-  verified_date: 2026-04-02
+  source_commit: 2a6e9f2a2066d80c072a7cc2cb644e35def9add3
+  verified_date: 2026-04-03
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: saorsa-core
   source_ref: main
-  source_commit: 6c5fb3cd67f621b4faeb9f6520a1498d3064b1d0
-  verified_date: 2026-04-02
+  source_commit: 75a663b60620096aa5989cf6e3b5040b79bc5ce9
+  verified_date: 2026-04-03
   verification_mode: current-merged-truth
 -->
 <!-- verification:
   source_repo: saorsa-transport
   source_ref: main
-  source_commit: a81dbb5bc3c7929537873c90e7a10678993d415e
-  verified_date: 2026-04-02
+  source_commit: b2c2280b88adb94203554bd2c80cb0c0fcb8ce6a
+  verified_date: 2026-04-03
   verification_mode: current-merged-truth
 -->
 <!-- verification:
@@ -87,13 +87,20 @@ These interfaces target the same network, but one uses a local daemon and the ot
 
 ## Network and node layer
 
-The current `ant-node` crate is a thin wrapper around `saorsa-core::P2PNode`. It adds configuration, chunk storage, payment verification, upgrade handling, and node runtime management on top of the core P2P layer.
+The `ant-node` crate is a thin wrapper around `saorsa-core::P2PNode`. It adds configuration, chunk storage, payment verification, replication, upgrade handling, and node runtime management on top of the core P2P layer.
 
 In the repos used for this page, `ant-node` documents chunk storage as its active network data type.
 
 ## Routing and transport
 
-`saorsa-core` provides the P2P node, DHT, bootstrap handling, and trust system. `saorsa-transport` provides QUIC transport, NAT traversal, and the documented pure post-quantum transport layer centered on ML-KEM-768 and ML-DSA-65.
+`saorsa-core` provides the P2P node, DHT, bootstrap handling, trust system, and routing-table logic around typed addresses and peer identity. `saorsa-transport` provides QUIC transport, NAT traversal, address discovery, and relay fallback where direct hole punching is not enough.
+
+The transport story includes:
+
+- observed-address discovery and address propagation across the network
+- peer-ID-based hole-punch coordination
+- relay fallback for some CGNAT cases
+- QUIC-based post-quantum transport centered on ML-KEM-768 and ML-DSA-65
 
 ## Data path
 

docs/cli-reference/ant-core-library.md

@@ -3,16 +3,16 @@
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 727a75c46bebc6d5948ea7754debd4220ead9400
-  verified_date: 2026-04-02
+  source_commit: 796d0df75d748419a004aec6f5e288b41d8b496e
+  verified_date: 2026-04-04
   verification_mode: current-merged-truth
 -->
 
 `ant-core` is the native Rust library for building directly on Autonomi without the daemon.
 
 ## Install
 
-The current repo README documents `ant-core` as a local dependency from an `ant-client` checkout:
+Use `ant-core` as a local dependency from an `ant-client` checkout:
 
 ```toml
 [dependencies]
@@ -93,6 +93,14 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 }
 ```
 
+## External signer flows
+
+The native Rust library exposes both wave-batch and Merkle-batch external payment helpers.
+
+For wave-batch uploads, `data_prepare_upload`, `file_prepare_upload`, and `finalize_upload` prepare the upload, collect quotes, and later store the chunks after an external signer returns transaction hashes.
+
+For Merkle batches, `prepare_merkle_batch_external` builds the batch data needed for the on-chain call, and `finalize_merkle_batch` turns the winning pool hash back into per-chunk proofs.
+
 ## Key types
 
 | Type | Description |
@@ -103,6 +111,36 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 | `ant_core::data::DataMap` | Private retrieval map for uploaded data |
 | `ant_core::data::LocalDevnet` | Local development helper |
 | `ant_core::data::Wallet` | EVM wallet used for paid operations |
+| `ant_core::data::PreparedUpload` | Two-phase upload state used by external-signer flows |
+| `ant_core::data::ExternalPaymentInfo` | External payment details for prepared uploads |
+| `ant_core::data::PreparedMerkleBatch` | Prepared Merkle batch data for external signing |
+
+## External signer example
+
+```rust
+use ant_core::data::{Client, ClientConfig, ExternalPaymentInfo};
+use bytes::Bytes;
+use std::collections::HashMap;
+
+#[tokio::main]
+async fn main() -> Result<(), Box<dyn std::error::Error>> {
+    let client = Client::connect(&["1.2.3.4:12000".parse()?], ClientConfig::default()).await?;
+    let prepared = client.data_prepare_upload(Bytes::from("hello autonomi")).await?;
+
+    match &prepared.payment_info {
+        ExternalPaymentInfo::WaveBatch { payment_intent, .. } => {
+            println!("Need to pay {} atto", payment_intent.total_amount);
+        }
+        ExternalPaymentInfo::Merkle { prepared_batch, .. } => {
+            println!("Merkle depth: {}", prepared_batch.depth);
+        }
+    }
+
+    let tx_hashes: HashMap<_, _> = HashMap::new();
+    let _ = tx_hashes;
+    Ok(())
+}
+```
 
 ## Error handling
 
@@ -145,5 +183,5 @@ async fn main() -> Result<(), Box<dyn std::error::Error>> {
 ## Related pages
 
 - [Developing in Rust](../rust-reference/overview.md)
-- [Build Directly in Rust](../getting-started/build-directly-in-rust.md)
+- [Build in Rust with ant-core](../getting-started/build-directly-in-rust.md)
 - [Rust SDK](../sdk-reference/language-bindings/rust.md)

docs/cli-reference/command-reference.md

@@ -3,8 +3,8 @@
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 727a75c46bebc6d5948ea7754debd4220ead9400
-  verified_date: 2026-04-02
+  source_commit: 796d0df75d748419a004aec6f5e288b41d8b496e
+  verified_date: 2026-04-04
   verification_mode: current-merged-truth
 -->
 

docs/cli-reference/overview.md

@@ -3,8 +3,8 @@
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 727a75c46bebc6d5948ea7754debd4220ead9400
-  verified_date: 2026-04-02
+  source_commit: 796d0df75d748419a004aec6f5e288b41d8b496e
+  verified_date: 2026-04-04
   verification_mode: current-merged-truth
 -->
 
@@ -18,7 +18,7 @@ Use the CLI when you want:
 - direct control over bootstrap peers, devnet manifests, and EVM network selection
 - shell-first automation or operational workflows
 
-If you want SDK ergonomics in other languages, use the SDK path instead. If you want daemon-free programmatic Rust access, see [Developing in Rust](../rust-reference/overview.md).
+If you want SDK ergonomics in other languages, use the SDKs instead. If you want daemon-free programmatic Rust access, see [Developing in Rust](../rust-reference/overview.md).
 
 ## CLI shape
 
@@ -44,7 +44,7 @@ It also accepts global flags such as:
 
 ## Installation
 
-The current README documents install scripts for Linux, macOS, and Windows, plus source builds from the repo.
+Install scripts are available for Linux, macOS, and Windows, and you can also build the CLI from source.
 
 ```bash
 curl -fsSL https://raw.githubusercontent.com/WithAutonomi/ant-client/main/install.sh | bash
@@ -54,7 +54,7 @@ curl -fsSL https://raw.githubusercontent.com/WithAutonomi/ant-client/main/instal
 
 The CLI, SDK, and native Rust paths reach the same network, but they have different shapes:
 
-| | SDK path | CLI path | Native Rust path |
+| | SDKs | CLI | Native Rust |
 |---|---|---|---|
 | Interface model | daemon + SDK bindings | direct CLI | direct Rust library |
 | Best for | app development in many languages | shell workflows and operations | daemon-free Rust development |

docs/core-concepts/data-types.md

@@ -10,8 +10,8 @@
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 727a75c46bebc6d5948ea7754debd4220ead9400
-  verified_date: 2026-04-02
+  source_commit: 796d0df75d748419a004aec6f5e288b41d8b496e
+  verified_date: 2026-04-04
   verification_mode: current-merged-truth
 -->
 
@@ -86,7 +86,7 @@ This makes DataMap handling one of the main differences between public and priva
 
 ## Practical example
 
-The current tooling maps cleanly onto these surfaces:
+The tooling maps cleanly onto these surfaces:
 
 - use `POST /v1/data/public` or `client.data_put_public(...)` for public in-memory bytes
 - use `POST /v1/data/private` or `client.data_put_private(...)` for private in-memory bytes

docs/core-concepts/key-derivation.md

@@ -15,25 +15,25 @@
   verification_mode: current-merged-truth
 -->
 
-In the repos in scope, key derivation appears as a generic cryptographic primitive in `saorsa-pqc` and as domain-separated signing contexts in `ant-keygen`.
+In the repos covered here, key derivation appears as a generic cryptographic primitive in `saorsa-pqc` and as domain-separated signing contexts in `ant-keygen`.
 
 ## Why it matters
 
-This page is narrower than the earlier draft version. The sources in scope support HKDF and signing-context separation, but they do not document one Autonomi-wide master-key hierarchy for storage, signing, and payments.
+This page focuses on the parts of key derivation that are actually documented in the current stack. Autonomi uses HKDF primitives and signing-context separation, but it does not define one unified key hierarchy for storage, signing, and payments.
 
 ## How it works
 
 ### HKDF in saorsa-pqc
 
-The current `saorsa-pqc` README documents HKDF-SHA3-256 and HKDF-SHA3-512 as available key-derivation primitives.
+`saorsa-pqc` provides HKDF-SHA3-256 and HKDF-SHA3-512 as key-derivation primitives.
 
 That means the crypto library can derive new key material from shared secrets or existing key material, but the repo does not by itself define how application-level Autonomi keys should be organized.
 
 ### Domain separation in ant-keygen
 
 `ant-keygen` uses a `--context` flag for signing and verification. That context string keeps one signing domain separate from another, so the same raw key material is not reused blindly across unrelated purposes.
 
-The current default context is `ant-node-release-v1`.
+The default context is `ant-node-release-v1`.
 
 ## Practical example
 

docs/core-concepts/overview.md

@@ -10,8 +10,8 @@
 <!-- verification:
   source_repo: ant-client
   source_ref: main
-  source_commit: 727a75c46bebc6d5948ea7754debd4220ead9400
-  verified_date: 2026-04-02
+  source_commit: 796d0df75d748419a004aec6f5e288b41d8b496e
+  verified_date: 2026-04-04
   verification_mode: current-merged-truth
 -->
 <!-- verification:
@@ -45,13 +45,13 @@ Read more in [Self-Encryption](self-encryption.md).
 
 ## Post-quantum cryptography
 
-The cryptography stack in scope uses ML-DSA-65 for signatures and ML-KEM-768 for key encapsulation. Those algorithms matter most when you are reasoning about network identity, transport security, or the broader security model.
+The cryptography stack uses ML-DSA-65 for signatures and ML-KEM-768 for key encapsulation. Those algorithms matter most when you are reasoning about network identity, transport security, or the broader security model.
 
 Read more in [Post-Quantum Cryptography](post-quantum-cryptography.md).
 
 ## Payment model
 
-Autonomi is designed around pay-once, immutable storage. Upload flows are wallet-backed writes: you pay when you store data, then retrieve it later without a separate retrieval payment flow in the current developer tooling.
+Autonomi is designed around pay-once, immutable storage. Uploads are wallet-backed writes: you pay when you store data, then retrieve it later without recurring storage fees or retrieval payments.
 
 Read more in [Payment Model](payment-model.md).