API docs parity: Node.js / TypeScript

## Node.js / TypeScript API Docs

**Parent epic:** #1653

**Doc format:** [TSDoc](https://tsdoc.org/) / [TypeDoc](https://typedoc.org/) comments (`/** ... */` with `@param`, `@returns`, etc.). TypeDoc generates HTML from these.

**Culture:** Weaker than Java. npm does **not** require a docs artifact to publish. Many packages ship only a README + inline types (the `.d.ts` files *are* the docs for many TS consumers via IDE hover). Publishing standalone API docs is opt-in.

**Hosting analogues:**

| Service | How it works |
|---------|-------------|
| [typedoc.org](https://typedoc.org/) | Generator, not host |
| [tsdocs.dev](https://tsdocs.dev/) | Closest to javadoc.io — auto-generates docs from any npm package's types on demand |
| GitHub Pages / custom | Many projects self-host (e.g. `docs/` folder or CI-published site) |

**Key difference from Java:** No registry-mandated doc artifact. `tsdocs.dev` synthesizes docs from published `.d.ts` type declarations rather than a pre-built doc jar.

### Additional research: tsdocs.dev fragility

As of 2026-06-13, tsdocs.dev returns **502 Bad Gateway** across the board — both the homepage and package-specific URLs (e.g. `https://tsdocs.dev/docs/@github/copilot-sdk`). The service is completely down, not just a homepage glitch.

This reinforces the fragility of the TypeScript ecosystem's doc hosting: tsdocs.dev is a volunteer-run third-party project, not backed by npm or Microsoft. It has had reliability issues before. There is no npm Inc. or TypeScript team commitment keeping it running — unlike docs.rs (Rust team) or pkg.go.dev (Go team), which are first-party infrastructure with SLAs.

In practice, for the `@github/copilot-sdk` npm package, the realistic API-docs options are:

1. **Self-host TypeDoc output** (e.g., GitHub Pages from CI) — most reliable
2. **Rely on `.d.ts` hover docs in IDEs** — what most TS consumers actually use day-to-day
3. **tsdocs.dev** — when it's up, which apparently is not guaranteed

**As a Java Champion perspective:** Java's Maven Central mandate for javadoc jars means API docs are a first-class, always-available artifact. This is particularly important in an era where AI is writing code — maintainability depends on discoverable, reliably-hosted documentation. The TypeScript ecosystem lacks this guarantee, making self-hosted docs a necessity rather than optional.

Start by reading parent epic #1653 and the issue's discussion of TSDoc, TypeDoc, tsdocs.dev, GitHub Pages, and published .d.ts files. The issue names no repository files, tests, or implementation entry point; the work is complete only when the project’s API documentation approach and deliverable are clearly decided.

Written by the indexing model from the issue text.