docs: fix CLI reference, programmatic API example, and without-openapi syntax errors

.changeset/docs-review-corrections.md

@@ -0,0 +1,5 @@
+---
+"counterfact": patch
+---
+
+Fix documentation inconsistencies: complete CLI reference table, correct programmatic API example in FAQ, fix invalid JS syntax and broken link in without-openapi guide, and fix formatting in programmatic-api guide.

docs/faq.md

@@ -221,15 +221,38 @@ No. Counterfact only writes files that don't already exist. Your custom route lo
 
 ## Can I use it programmatically (not via the CLI)?
 
-Yes. Import `counterfact` and call it with options:
+Yes. Import `counterfact` and pass a `Config` object:
 
 ```ts
 import { counterfact } from "counterfact";
 
-await counterfact("openapi.yaml", "api", { port: 4000, serve: true });
+const { start } = await counterfact({
+  openApiPath: "openapi.yaml",
+  basePath: "api",
+  port: 4000,
+  startServer: true,
+  startRepl: false,
+  generate: { routes: false, types: false },
+  watch: { routes: false, types: false },
+  alwaysFakeOptionals: false,
+  buildCache: false,
+  proxyPaths: new Map(),
+  proxyUrl: "",
+  prefix: "",
+  startAdminApi: false,
+  validateRequests: true,
+  validateResponses: true,
+});
+
+const { stop } = await start({
+  startServer: true,
+  generate: { routes: false, types: false },
+  watch: { routes: false, types: false },
+  buildCache: false,
+});
 ```
 
-This makes Counterfact easy to embed in test setups — start a server in `beforeAll`, stop it in `afterAll`, and run real HTTP requests against it in your tests.
+This makes Counterfact easy to embed in test setups — start a server in `beforeAll`, stop it in `afterAll`, and run real HTTP requests against it in your tests. See the [Programmatic API guide](./features/programmatic-api.md) for a complete example.
 
 ---
 

docs/features/programmatic-api.md

@@ -134,7 +134,9 @@ const { start } = await counterfact(config, [
 ```
 
 
-## Return value of `counterfact()`| Property          | Type                           | Description                                                                                                                  |
+## Return value of `counterfact()`
+
+| Property          | Type                           | Description                                                                                                                  |
 | ----------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
 | `contextRegistry` | `ContextRegistry`              | Registry of all context objects keyed by path. Call `.find(path)` to get the context for a given route prefix.               |
 | `registry`        | `Registry`                     | Registry of all loaded route modules.                                                                                        |

docs/features/without-openapi.md

@@ -22,7 +22,7 @@ In the file where the code is generated, you should find a directory -- initiall
 
 ```js
 // hello/world.js
-export const GET() {
+export function GET() {
     return "World says hello!";
 }
 ```
@@ -31,18 +31,18 @@ If part of the path is variable, name the file or directory where the variable p
 
 ```js
 //{greeting}/{subject}.js
-export const GET($) {
+export function GET($) {
     return `${$.path.subject} says ${$.path.greeting}!`;
 }
 ```
 
-For more information on the `$` object, see the [usage guide](./usage.md).
+For more information on the `$` object, see the [reference guide](../reference.md).
 
 ## Now that you know how to work without an OpenAPI doc, here's why you should have one anyway
 
 OpenAPI is the de-facto standard for documenting REST APIs. Counterfact is just one of [hundreds of tools](https://openapi.tools/) that use it. And if you pass Counterfact an OpenAPI doc, it will save you a lot of time by automatically generating default type-safe implementations of each API, with powerful context-sensitive autocomplete when you want to make changes.
 
-Not many people love writing documentation. Fewer people still love working on APIs that are not documented. Counterfact makes documentation useful, with immediate ROI, so that so that maintaining the docs is just as rewarding as writing code.
+Not many people love writing documentation. Fewer people still love working on APIs that are not documented. Counterfact makes documentation useful, with immediate ROI, so that maintaining the docs is just as rewarding as writing code.
 
 ## See also
 

docs/reference.md

@@ -294,23 +294,28 @@ npx counterfact@latest [spec] [output] [options]
 
 | Flag | Default | Description |
 | --- | --- | --- |
-| `--port <n>` | `3100` | HTTP server port |
+| `-p, --port <number>` | `3100` | HTTP server port |
 | `-o, --open` | `false` | Open browser on start |
-| `-g, --generate` | `false` | Generate files and exit |
-| `-w, --watch` | `false` | Regenerate on spec changes |
+| `-g, --generate` | `false` | Generate all code (routes and types) |
+| `-w, --watch` | `false` | Generate and watch all code for changes |
 | `-s, --serve` | `false` | Start the server |
 | `-r, --repl` | `false` | Start the REPL |
+| `-b, --build-cache` | `false` | Build the cache of compiled routes and types |
 | `--spec <path>` | _(positional arg)_ | Path or URL to the OpenAPI document |
 | `--proxy-url <url>` | _(none)_ | Default upstream for the proxy |
 | `--prefix <path>` | _(none)_ | Global path prefix (e.g. `/api/v1`) |
-| `--no-validate-request` | `false` | Skip OpenAPI request validation |
-| `--no-validate-response` | `false` | Skip OpenAPI response header validation |
+| `--no-validate-request` | — | Disable OpenAPI request validation |
+| `--no-validate-response` | — | Disable OpenAPI response validation |
 | `--generate-types` | `false` | Generate types only |
 | `--generate-routes` | `false` | Generate routes only |
 | `--watch-types` | `false` | Watch and regenerate types only |
 | `--watch-routes` | `false` | Watch and regenerate routes only |
 | `--always-fake-optionals` | `false` | Include optional fields in random responses |
-| `-b, --build-cache` | `false` | Pre-compile routes and types without starting the server |
+| `--prune` | `false` | Remove route files that no longer exist in the spec |
+| `--no-admin-api` | — | Disable the Admin API at `/_counterfact/api/*` |
+| `--admin-api-token <token>` | _(none)_ | Bearer token required for Admin API endpoints |
+| `--no-update-check` | — | Disable the npm update check on startup |
+| `--config <path>` | `counterfact.yaml` | Path to a config file |
 
 Run `npx counterfact@latest --help` for the full list.