Generate the API reference; export the types public signatures name

.github/workflows/ci.yml

@@ -56,6 +56,12 @@ jobs:
       - name: Check for unused code
         run: npm run knip
 
+      # The API reference, with warnings as errors: a broken `{@link}`, or a
+      # type a public signature names that the package does not export, fails
+      # here rather than shipping as a hole in the documentation.
+      - name: Generate the API reference
+        run: npm run docs:api
+
   # Real Extension Host. The only lane that can verify the shutdown contract the
   # whole design rests on -- and the one that found VS Code disposes
   # context.subscriptions *during* deactivate(), not after it.

.gitignore

@@ -64,3 +64,5 @@ mkdocs/
 # CLAUDE.md
 CLAUDE.md
 
+# Generated API reference (`npm run docs:api`)
+docs/api/

CHANGELOG.md

@@ -82,6 +82,19 @@ Pre-1.0 releases followed it in spirit; their breaking changes are marked **Brea
   it concerns, and the JSON that would settle it when the fix is mechanical.
   The assertion is unchanged and built on top of it.
 
+- **An API reference, generated from the JSDoc.** `npm run docs:api` renders
+  every public entry point with TypeDoc, and CI runs it with warnings as
+  errors. Setting that up found what the warnings exist to find: types that
+  public signatures name — the port a tree provider returns, the surface a fake
+  hands back, the options `setting.boolean` takes, the reason on a cancelled
+  operation — which the package never exported, so a consumer could receive one
+  and not be able to write its type. They are exported now, from the entry
+  whose signatures name them. `{@link}` tags that pointed at internal symbols
+  became plain code. `ApplicationPlan`'s members are marked internal: the plan
+  is a handle for `createTestHost` and `describePlan`, and `describePlan` is
+  its readable form. The reference is not hosted yet; the output is under
+  `docs/api/`, ignored by git.
+
 ### Changed
 
 - **`defineExtension` is single-use, like the extension host it serves.** A

CONTRIBUTING.md

@@ -42,8 +42,9 @@ npm run test:coverage   # the same suite, with the coverage gate
 npm run lint            # type-aware ESLint over src + tests, --max-warnings 0
 npm run format          # prettier
 npm run knip            # dead code
+npm run docs:api        # TypeDoc into docs/api; warnings are errors
 npm run verify:package  # pack, install into a throwaway consumer, import every subpath
-npm run quality         # typecheck + lint + test:coverage + knip — the gate CI runs
+npm run quality         # typecheck + lint + test:coverage + knip + docs:api — the gate CI runs
 ```
 
 `tsc -b --noEmit` does not work (TS6310: project references need `composite`, and

README.md

@@ -257,8 +257,10 @@ Values you pass around: `ok` `err` `unwrap` `mapResult` and the `s.*` schema
 builders; `FrameworkError` with `userError` / `validationError` / `classifyError`
 / `isCancellation`; `DisposableCollection` and `createScope`.
 
-Full signatures live in the `.d.ts` files and the JSDoc on each export; a
-generated API reference is not built yet.
+Full signatures live in the `.d.ts` files and the JSDoc on each export.
+`npm run docs:api` renders that JSDoc into an API reference under `docs/api/`
+(TypeDoc); CI runs it with warnings as errors, so a broken link or a type a
+public signature names but the package does not export cannot ship.
 
 ---
 
@@ -308,7 +310,7 @@ trusted for things it cannot do.
 - **The Test Host does not reproduce VS Code**: it renders no UI, interprets no contribution point, and does not substitute a direct `import "vscode"`
 - **No editor events yet**: `Editors` hands you the active editor and cross-file edits, but there is no `onDidChangeActive` / `onDidChangeSelection` / `onDidChangeDocument`; subscribing means reaching for `vscode` directly and disposing by hand, which is the one place the single-cleanup-owner rule leaks
 - **No log-level filtering, deliberately**: the framework writes to a `LogOutputChannel` and VS Code owns the level — per channel, persisted, in the Output panel. An extension cannot raise its own channel's level, so a `logLevel` setting of your own can only ever make the log quieter
-- **No generated API reference yet**, and no step-by-step migration guide from 2.x
+- **No hosted API reference yet** — it is generated from the JSDoc (`npm run docs:api`) but not published — and no step-by-step migration guide from 2.x
 
 ---
 

package.json

@@ -96,6 +96,7 @@
     "lint-staged": "^17.3.0",
     "prettier": "^3.9.6",
     "rimraf": "^6.1.3",
+    "typedoc": "^0.28.20",
     "typescript": "~6.0.3",
     "typescript-eslint": "^8.66.0",
     "vitest": "^4.1.10"
@@ -114,12 +115,13 @@
     "format": "prettier --write \"{src,tests,fixtures,docs}/**/*.ts\" \"{bin,scripts,fixtures,tests}/**/*.{mjs,cjs}\"",
     "format:check": "prettier --check \"{src,tests,fixtures,docs}/**/*.ts\" \"{bin,scripts,fixtures,tests}/**/*.{mjs,cjs}\"",
     "knip": "knip",
+    "docs:api": "typedoc",
     "verify:package": "node scripts/verify-package.mjs",
     "fixture:build": "node fixtures/extension-host/build.mjs",
     "fixture:build:web": "node fixtures/web-extension/build.mjs",
     "test:eh": "npm run build && npm run fixture:build && node fixtures/extension-host/run-test.mjs",
     "test:web": "npm run build && npm run fixture:build:web && node fixtures/web-extension/run-test.mjs",
-    "quality": "npm run format:check && npm run typecheck && npm run lint && npm run test:coverage && npm run knip"
+    "quality": "npm run format:check && npm run typecheck && npm run lint && npm run test:coverage && npm run knip && npm run docs:api"
   },
   "keywords": [
     "vscode",