--- README.md.old	2026-05-16 16:26:13.924736709 -0400
+++ README.md	2026-05-16 16:26:15.624707054 -0400
@@ -190,13 +190,6 @@
 a === b // true
 ```
 
-### fun.FunStream
-
-Exactly the same as `stream.PassThrough` but with fun added.  `fun()` is
-mostly the same as `new fun.FunStream()`.  (The former will use Bluebird for
-promises if available but fallback to system promises.  The latter has no
-magic and just uses system promises.)
-
 ### require('funstream/fun-stream').mixin
 
 The core extension mechanism (otherwise unneeded).  It adds fun to an
@@ -229,21 +222,112 @@
 NOTE: Not all streams emit a `close` event and if you use this on a stream
 that does not then it will never resolve.
 
 ### .async() → this
 ### .sync() → this
 
 Sets the stream `async` stream option to true and false respectively.
 
+When you set `.async()` on a stream, all subsequent operations will be
+assumed to use async callbacks (promises or callbacks). This is useful
+when you want to skip auto-detection:
+
+```js
+fun([1, 2, 3])
+  .async()
+  .map(v => Promise.resolve(v * 2)) // treated as async (autodetect would fail)
+```
+
 ### .async(todo) → FunStream
 ### .sync(todo) → FunStream
 
 Runs `todo` with a stream with the appropriate `async` option set.  The
-returned value is restored to the previous setting.
+returned value of `todo` becomes the new stream, with the async mode restored
+to the prior setting.
+
+`async(fn)` temporarily switches a stream into async mode to run `fn`,
+then restores the original mode. This is useful when you want a chain of
+operations to run in async mode without affecting downstream operations:
 
+```js
+fun([1,2,3])
+  .filter(n => n % 2 === 0)                  // sync (auto-detected)
+  .async(st => st.map(v => Promise.resolve(v * 2)))  // async temporarily
+  .filter(n => n > 2)                        // back to sync
 ```
-fun([1,2,3])
-  .filter(async n => n > 0)
-  .sync(str => str.filter(n => n < 3).map(n => n * 2))
-```
 
 ### .fun.ended() → Promise