docs: describe package contents

.vitepress/config.mts

@@ -41,6 +41,7 @@ export default defineConfig({
             {text: 'API Reference', link: '/api'},
             {text: 'Configuration', link: '/configuration'},
             {text: 'CLI Usage', link: '/cli'},
+            {text: 'Package', link: '/package'},
             {text: 'Migration from v7', link: '/migration-from-v7'},
           ],
         },

migration-from-v7.md

@@ -2,7 +2,7 @@
 
 [v8.0.0 release](https://github.com/google/zx/releases/tag/8.0.0) brought many features, improvements and fixes, but also has introduced a few breaking changes.
 
-1. `$.verbose` is set to `false` by default, but errors are still printed to `stderr. Set `$.quiet = true` to suppress any output.
+1. `$.verbose` is set to `false` by default, but errors are still printed to `stderr`. Set `$.quiet = true` to suppress any output.
 ```js
 $.verbose = true // everything works like in v7
 

package.md

@@ -0,0 +1,38 @@
+# Package
+
+## Hybrid
+zx is distributed as a [hybrid package](https://2ality.com/2019/10/hybrid-npm-packages.html): it provides both CJS an ESM entry points.
+
+```js
+import { $ } from 'zx'
+
+const { $ } = require('zx')
+```
+
+It has also built-in TypeScript libdefs.
+
+```ts
+import { type Options } from 'zx'
+
+const opts: Options = {
+  quiet: true,
+  timeout: '5s'
+}
+```
+
+## Bundled
+
+We use [esbuild](https://dev.to/antongolub/how-and-why-do-we-bundle-zx-1ca6) to produce a static build that allows us to solve several issues at once:
+* Reduce the pkg size and install time.
+* Make npx (yarn dlx / bunx) invocations reproducible.
+* Provide support for wide range of Node.js versions: from 12 to 22.
+* Make auditing easier: complete code in one place.
+
+## Composite
+
+zx exports several entry points adapted for different use cases:
+* `zx` – the main entry point, provides all the features.
+* `zx/global` – to populate the global scope with zx functions.
+* `zx/cli` – to run zx scripts from the command line.
+* `zx/core` – to use zx template spawner as part of 3rd party libraries with alternating set of utilities.
+