refine docs

docs/async.md

@@ -7,15 +7,15 @@ nav_order: 5
 
 # Async
 
-**Async** pattern allows the `post()` step to be asynchronous (`post_async()`). This is especially helpful if you need to **await** something in `post_async()`—for example, user feedback or external async requests.
+**Async** pattern allows the `post()` step to be asynchronous: `post_async()`. This is especially helpful if you need to `await` something—for example, user feedback or external async requests.
 
-**Warning**: Only `post()` is async. `prep()` and `exec()` must be sync (often used for LLM calls).
+**⚠️ Warning**: Only `post_async()` is async. `prep()` and `exec()` must be sync.
 
 ---
 
 ## 1. AsyncNode
 
-Below is a minimal **AsyncNode** that calls an LLM in `exec()` (sync) and then awaits user feedback in `post_async()`:
+Below is a minimal **AsyncNode** that calls an LLM in `exec()` to summarize texts, and then awaits user feedback in `post_async()`:
 
 ```python
 class SummarizeThenVerify(AsyncNode):
@@ -32,6 +32,9 @@ class SummarizeThenVerify(AsyncNode):
             return "deny"
 ```
 
+- `exec()`: Summarizes text (sync LLM call).
+- `post_async()`: Waits for user approval (async).
+
 ---
 
 ## 2. AsyncFlow
@@ -56,9 +59,3 @@ async def main():
 asyncio.run(main())
 ```
 
-- **SummarizeThenVerify**: 
-  - `exec()`: Summarizes text (sync LLM call).
-  - `post_async()`: Waits for user approval.
-- **Finalize**: Makes a final LLM call and prints the summary.
-- If user denies, the flow loops back to **SummarizeThenVerify**.
-

docs/communication.md

@@ -15,9 +15,9 @@ Nodes and Flows **communicate** in two ways:
 If you know memory management, **Shared Store** is like a **heap** shared across function calls, while **Params** is like a **stack** assigned by parent function calls.
 
 
-### Why Not Message Passing?
+### Why Not Use Other Communication Models like Message Passing?
 
-**Message passing** can work for simple DAGs (e.g., for data pipelines), but with **nested graphs** (Flows containing Flows, repeated or cyclic calls), routing messages becomes hard to maintain. A shared store keeps the design simpler and easier.
+**Message passing** works well for simple DAGs (e.g., for data pipelines), but with **nested graphs** (Flows containing Flows, repeated or cyclic calls), routing messages becomes hard to maintain. A shared store keeps the design simple and easy.
 
 ---
 
@@ -30,8 +30,7 @@ A shared store is typically an in-mem dictionary, like:
 shared = {"data": {}, "summary": {}, "config": {...}, ...}
 ```
 
-It can also contain local file handlers, DB connections, or a combination for persistence.  
+It can also contain local file handlers, DB connections, or a combination for persistence. We recommend deciding the data structure or DB schema first based on your app requirements.
-We recommend deciding the data structure or DB schema in advance based on your app requirements.
 
 ### Example
 
@@ -77,8 +76,7 @@ No special data-passing—just the same `shared` object.
 
 **Params** let you store **per-Node** or **per-Flow** config that doesn’t need to live in the global store. They are:
 - **Immutable** during a Node’s run cycle (i.e., they don’t change mid-`prep`, `exec`, `post`).
-- **Set** via `set_params()`.  
+- **Set** via `set_params()`. **⚠️ Warning** Only set the uppermost Flow params because others will be overwritten by the parent Flow. If you need to set child node params, see [Batch](./batch.md).
-  ⚠️ Only set the uppermost Flow params because others will be overwritten by the parent Flow. If you need to set child node params, see [Batch](./batch.md).
 - **Cleared** and updated each time a parent Flow calls it.
 
 Typically, **Params** are identifiers (e.g., file name, page number). Use them to fetch the task you assigned or write to a specific part of the shared store.

docs/node.md

@@ -20,7 +20,7 @@ A **Node** is the smallest building block of Mini LLM Flow. Each Node has three
    - Returns `exec_res`, which is passed to `post()`.
 
 3. **`post(shared, prep_res, exec_res)`**  
-   - Optionally perform post-processing, such as writing results back to the `shared` store or deciding the next action.  
+   - Optionally writes results back to the `shared` store or decides the next action.  
    - Often used to finalize outputs, trigger next steps, or log results.  
    - Returns a **string** to specify the next action (`"default"` if nothing or `None` is returned).