Commit e6720f6

@@ -1,12 +1,39 @@
 # Shell
 
-zx is not aimed to replace the shell, but to provide a more convenient way to use it through JavaScript enhancements. It supplements the shell with a more powerful and expressive language, so some kind of bash/zsh is still required.
+[Bash](https://en.wikipedia.org/wiki/Bash_(Unix_shell)) is a fundamental part of the Unix ecosystem, and it is widely used for scripting and automation tasks. It provides a powerful set of built-in utils, operators, process controllers.
+Bash gives an efficient way to fine-tune the behavior: cmd aliases, context presets, custom functions, env injections, and more.
 
-zx provides several functions to help with setup:
+zx is not trying to replace bash, but to enhance it with JavaScript's capabilities:
+* Parallel execution
+* Data transformations
+* Exception handling
+* Conditional logic and loops
+
+```js
+#!/usr/bin/env zx
+import { $ } from 'zx'
+
+$.nothrow = true
+
+const repos = ['zx', 'webpod']
+const clones = repos
+  .map(n => $`git clone https://github.com/google/${n} ${n}-clone`)
+
+const results = await Promise.all(clones)
+const errors = results.filter(o => !o.ok).map(o => o.stderr.trim())
+console.log('errors', errors.join('\n'))
+
+for (p of clones) {
+  await p.pipe`cat > ${p.pid}.txt`
+}
+```
+
+## Bash and Pwsh
+There're many shell implementations. zx brings a few setup helpers:
 
 * [`useBash`](./api#usebash) switches to bash
-* [`usePowerShell`](./api#usepowershell) - PowerShell
-* [`usePwsh`](./api#usepwsh) - pwsh (PowerShell v7+)
+* [`usePowerShell`](./api#usepowershell) — PowerShell
+* [`usePwsh`](./api#usepwsh) — pwsh (PowerShell v7+)
 
 You can also set the shell directly via [JS API](./setup#bash), [CLI flags](./cli#shell) or [envars](./cli#environment-variables):
 
@@ -21,3 +48,6 @@ zx --shell /bin/zsh script.js
 ```bash
 ZX_SHELL=/bin/zsh zx script.js
 ```
+
+## zx = bash + js
+No compromise, take the best of both.

@@ -15,7 +15,7 @@
       "README.md",
       "LICENSE"
     ],
-    "limit": "121.60 kB",
+    "limit": "121.67 kB",
     "brotli": false,
     "gzip": false
   },
@@ -62,7 +62,7 @@
       "README.md",
       "LICENSE"
     ],
-    "limit": "868.15 kB",
+    "limit": "868.20 kB",
     "brotli": false,
     "gzip": false
   }

@@ -21,7 +21,7 @@ await $`mkdir /tmp/${name}`
 Bash is great, but when it comes to writing more complex scripts,
 many people prefer a more convenient programming language.
 JavaScript is a perfect choice, but the Node.js standard library
-requires additional hassle before using. The `zx` package provides
+requires additional hassle before using. No compromise, take the best of both. The `zx` package provides
 useful cross-platform wrappers around `child_process`, escapes arguments and
 gives sensible defaults.
 
@@ -45,7 +45,7 @@ See also [**zx@lite**](https://google.github.io/zx/lite).
     * Bun >= 1.0.0
     * Deno 1.x, 2.x
     * GraalVM Node.js
-* Some kind of bash or PowerShell
+* Some kind of [bash or PowerShell](https://google.github.io/zx/shell)
 * [Both CJS or ESM](https://google.github.io/zx/setup#hybrid) modules in [JS or TS](https://google.github.io/zx/typescript)