docs: describe shell issues (google#1128)

* docs: describe shell issues

closes google#1127

* chore: bump version to 8.4.1

* Update shell.md

---------

Co-authored-by: Anton Medvedev <anton@medv.io>

Author: antongolub

docs/.vitepress/config.mts

@@ -75,6 +75,7 @@ export default defineConfig({
           link: '/faq',
           items: [
             { text: 'Quotes', link: '/quotes' },
+            { text: 'Shell', link: '/shell' },
             { text: 'TypeScript', link: '/typescript' },
             { text: 'Markdown Scripts', link: '/markdown-scripts' },
             { text: 'Known Issues', link: '/known-issues' },

docs/shell.md

@@ -0,0 +1,23 @@
+# 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.
+
+zx provides several functions to help with setup:
+
+* [`useBash`](./api#usebash) switches to bash
+* [`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):
+
+```js
+$.shell = '/bin/zsh'
+```
+
+```bash
+zx --shell /bin/zsh script.js
+```
+
+```bash
+ZX_SHELL=/bin/zsh zx script.js
+```

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "zx",
-  "version": "8.4.0",
+  "version": "8.4.1",
   "description": "A tool for writing better scripts",
   "type": "module",
   "main": "./build/index.cjs",

package.json

@@ -839,12 +839,14 @@ try {
 
 function checkShell() {
   if (!$.shell)
-    throw new Error(`No shell is available: https://ï.at/zx-no-shell`)
+    throw new Error(`No shell is available: https://google.github.io/zx/shell`)
 }
 
 function checkQuote() {
   if (!$.quote)
-    throw new Error('No quote function is defined: https://ï.at/no-quote-func')
+    throw new Error(
+      'No quote function is defined: https://google.github.io/zx/quotes'
+    )
 }
 
 let cwdSyncHook: AsyncHook