Document Tokio migration companion

Author: eldryoth

docs/MIGRATION.md

@@ -213,9 +213,40 @@ expose `is_failed()` and fail closed after malformed Base64 input; unchecked
 `into_inner()` remains available for explicit recovery of the wrapped object
 after a decode error.
 
-The `tokio` feature is reserved for future async wrappers. It is currently
-inert and dependency-free; use the explicit `stream` feature for `std::io`
-wrappers.
+The core crate's `tokio` feature is reserved, inert, and dependency-free. For
+Tokio applications, use the optional `base64-ng-tokio` companion crate instead:
+
+```toml
+[dependencies]
+base64-ng = "1.3.3"
+base64-ng-tokio = "1.3.3"
+tokio = { version = "1.52.3", features = ["io-util"] }
+```
+
+```rust
+use base64_ng::STANDARD;
+use base64_ng_tokio::{encode_reader_to_writer_limited, EncoderReader, EncoderWriter};
+use tokio::io::{AsyncReadExt, AsyncWriteExt};
+
+# async fn example() -> std::io::Result<()> {
+let mut input = &b"hello"[..];
+let mut output = Vec::new();
+encode_reader_to_writer_limited(&STANDARD, &mut input, &mut output, 1024).await?;
+assert_eq!(output, b"aGVsbG8=");
+
+let mut reader = EncoderReader::new(&b"hello"[..], STANDARD);
+let mut streamed = Vec::new();
+reader.read_to_end(&mut streamed).await?;
+assert_eq!(streamed, b"aGVsbG8=");
+
+let mut writer = EncoderWriter::new(Vec::new(), STANDARD);
+writer.write_all(b"hello").await?;
+writer.shutdown().await?;
+let encoded = writer.into_inner()?;
+assert_eq!(encoded, b"aGVsbG8=");
+# Ok(())
+# }
+```
 
 ## Security Notes
 

release-notes/RELEASE_NOTES_1.3.3.md

@@ -44,6 +44,8 @@ wasm `simd128` runtime-dispatch profile with explicit runtime smoke evidence.
 - Aligned roadmap and README wording with the current async split: the core
   `tokio` feature remains inert, while `base64-ng-tokio` is the admitted
   async helper and streaming adapter surface.
+- Updated the migration guide with the same async split and a
+  `base64-ng-tokio` migration example.
 - Added release-gated wasm SIMD codegen evidence through
   `scripts/generate_wasm_simd_evidence.sh`, which emits test-harness LLVM IR
   with `target-feature=+simd128` when the wasm target is installed.