chore: make doc-kit friendly

.changeset/bootstrap-command.md

@@ -0,0 +1,5 @@
+---
+'@nodejs/doc-kit': minor
+---
+
+Add `doc-kit bootstrap [generators...]`

.changeset/install-command.md

@@ -0,0 +1,5 @@
+---
+'@nodejs/doc-kit': minor
+---
+
+Add `doc-kit install [generators...]`

.changeset/serve-command.md

@@ -0,0 +1,5 @@
+---
+'@nodejs/doc-kit': minor
+---
+
+Add `doc-kit serve`

README.md

@@ -46,16 +46,26 @@ $ node packages/core/bin/cli.mjs --help
 ```
 Usage: @nodejs/doc-kit [options] [command]
 
-CLI tool to generate the Node.js API documentation
+CLI tool to generate API documentation
 
 Options:
-  --log-level <level>  Log level (choices: "debug", "info", "warn", "error",
-                       "fatal", default: "info")
-  -h, --help           display help for command
+  --log-level <level>                  Log level (choices: "debug", "info",
+                                       "warn", "error", "fatal", default:
+                                       "info")
+  -h, --help                           display help for command
 
 Commands:
-  generate [options]   Generate API docs
-  help [command]       display help for command
+  bootstrap [options] [generators...]  Set up a project for doc-kit: a
+                                       configuration file wired to your
+                                       package.json, a documentation directory,
+                                       and the generator packages
+  generate [options]                   Generate API docs
+  install [options] [generators...]    Install the packages providing built-in
+                                       generators (defaults to the targets in
+                                       your configuration file)
+  serve [options]                      Generate API docs, serve them locally,
+                                       and regenerate on changes
+  help [command]                       display help for command
 ```
 
 ### `generate`
@@ -78,14 +88,14 @@ Options:
                                (json-simple, legacy-html, legacy-html-all,
                                man-page, legacy-json, legacy-json-all,
                                addon-verify, api-links, orama-db, llms-txt,
-                               sitemap, web) or an import specifier for a custom
-                               generator
+                               sitemap, html) or an import specifier for a
+                               custom generator
   --ignore <patterns...>       Ignore file patterns (glob)
   -o, --output <directory>     The output directory
   -p, --threads <number>       Number of threads to use (minimum: 1)
   --chunk-size <number>        Number of items to process per worker thread
                                (minimum: 1)
-  -v, --version <semver>       Target Node.js version
+  -v, --version <semver>       Target project version
   -c, --changelog <url>        Changelog URL or path
   --git-ref <ref>              Git ref
   --index <url>                index.md URL or path
@@ -94,6 +104,76 @@ Options:
   -h, --help                   display help for command
 ```
 
+### `serve`
+
+Generates the documentation, serves it locally, and regenerates whenever the
+input files change — the fastest way to preview docs while writing them. It
+accepts the same configuration options as `generate`, plus:
+
+```
+Options:
+  --port <number>              Preferred port (falls back to the next available
+                               one) (default: 3000)
+  --static                     Serve the existing output as-is, without
+                               generating or watching
+```
+
+### `bootstrap`
+
+Sets a project up end to end: a `doc-kit.config.mjs` wired to your
+`package.json`, a documentation directory (detected, or created with a starter
+page), a `.gitignore` entry for the output, and the generator packages
+installed. Prompts for its few decisions on a TTY; `--yes` accepts the
+defaults. A new project only needs:
+
+```sh
+npx doc-kit bootstrap && npx doc-kit serve
+```
+
+```
+Usage: @nodejs/doc-kit bootstrap [options] [generators...]
+
+Set up a project for doc-kit: a configuration file wired to your package.json, a
+documentation directory, and the generator packages
+
+Arguments:
+  generators                Built-in generator names (json-simple, legacy-html,
+                            legacy-html-all, man-page, legacy-json,
+                            legacy-json-all, addon-verify, api-links, orama-db,
+                            llms-txt, sitemap, html)
+
+Options:
+  -y, --yes                 Accept all defaults without prompting
+  --dir <path>              The documentation directory
+  -o, --output <directory>  The output directory (default: "out")
+  --force                   Overwrite an existing configuration file
+  -h, --help                display help for command
+```
+
+### `install`
+
+Installs the packages providing built-in generators (e.g. `doc-kit install html`
+installs `@nodejs/doc-kit-generator-react`). Without arguments, it installs
+whatever the `target` in your configuration file needs. The package manager is
+detected from the project lockfile.
+
+```
+Usage: @nodejs/doc-kit install [options] [generators...]
+
+Install the packages providing built-in generators (defaults to the targets in
+your configuration file)
+
+Arguments:
+  generators            Built-in generator names (json-simple, legacy-html,
+                        legacy-html-all, man-page, legacy-json, legacy-json-all,
+                        addon-verify, api-links, orama-db, llms-txt, sitemap,
+                        html)
+
+Options:
+  --config-file <path>  Config file
+  -h, --help            display help for command
+```
+
 ## Examples
 
 ### Legacy
@@ -126,5 +206,5 @@ npx doc-kit generate \
 > In order to use the search functionality, you _must_ serve the output directory.
 >
 > ```sh
-> npx serve out
+> npx doc-kit serve --static -o out
 > ```

docs/cli.md

@@ -0,0 +1,94 @@
+# CLI
+
+The `doc-kit` command-line interface. Every option that maps to
+configuration can also live in a [configuration file](./configuration.md);
+when both are present, CLI flags win (rule of specifity).
+
+```sh
+npx doc-kit [command] [options]
+```
+
+One option applies to every command:
+
+| Option                | Description                                            |
+| --------------------- | ------------------------------------------------------ |
+| `--log-level <level>` | `debug`, `info` (default), `warn`, `error`, or `fatal` |
+
+## `doc-kit bootstrap`
+
+```sh
+npx doc-kit bootstrap [options] [generators...]
+```
+
+Sets a project up end to end: a `doc-kit.config.mjs` wired to your
+`package.json`, a documentation directory (detected, or created with a
+starter page), a `.gitignore` entry for the output, and the generator
+packages installed. On a terminal it prompts for its few decisions;
+otherwise (or with `--yes`) it accepts the defaults.
+
+| Option                 | Description                                   |
+| ---------------------- | --------------------------------------------- |
+| `[generators...]`      | Built-in generator names. **Default:** `html` |
+| `-y`, `--yes`          | Accept all defaults without prompting         |
+| `--dir <path>`         | The documentation directory                   |
+| `-o`, `--output <dir>` | The output directory. **Default:** `out`      |
+| `--force`              | Overwrite an existing configuration file      |
+
+## `doc-kit generate`
+
+```sh
+npx doc-kit generate [options]
+```
+
+Runs the generators and writes their output. Requires a `target` and an
+`input`, from flags or the configuration file.
+
+| Option                        | Description                                                   |
+| ----------------------------- | ------------------------------------------------------------- |
+| `--config-file <path>`        | Use a specific configuration file instead of searching        |
+| `-i`, `--input <patterns...>` | Input file patterns (glob)                                    |
+| `-t`, `--target <name...>`    | Generator name(s), or import specifiers for custom generators |
+| `--ignore <patterns...>`      | Input patterns to skip                                        |
+| `-o`, `--output <dir>`        | The output directory                                          |
+| `-v`, `--version <semver>`    | The version of the project being documented                   |
+| `-c`, `--changelog <url>`     | Changelog URL or path (release history for version selectors) |
+| `--git-ref <ref>`             | Git ref used in source links                                  |
+| `--index <url>`               | `index.md` URL or path                                        |
+| `--minify`                    | Minify the output                                             |
+| `--type-map <url>`            | Type map URL or path (custom type-name → URL links)           |
+| `-p`, `--threads <n>`         | Worker threads to use (minimum 1)                             |
+| `--chunk-size <n>`            | Items per worker thread (minimum 1)                           |
+
+## `doc-kit serve`
+
+```sh
+npx doc-kit serve [options]
+```
+
+Generates the documentation, serves it locally, and regenerates whenever
+input files change — the writing loop. Accepts every `generate` option,
+plus:
+
+| Option            | Description                                                            |
+| ----------------- | ---------------------------------------------------------------------- |
+| `--port <number>` | Preferred port, falling back to the next free one. **Default:** `3000` |
+| `--static`        | Serve the existing output as-is, without generating or watching        |
+
+`--static` is also the production preview: it serves any built output
+directory over HTTP, which the `html` output requires.
+
+## `doc-kit install`
+
+```sh
+npx doc-kit install [generators...]
+```
+
+Installs the packages providing built-in generators — `doc-kit install html`
+installs `@nodejs/doc-kit-generator-react`. With no arguments, it installs
+whatever the `target` in your configuration file needs. The package manager
+is detected from your lockfile (npm, pnpm, yarn, or bun).
+
+| Option                 | Description                                            |
+| ---------------------- | ------------------------------------------------------ |
+| `[generators...]`      | Built-in generator names                               |
+| `--config-file <path>` | Use a specific configuration file instead of searching |