Ship a generated single-file API reference for LLM agents

.changeset/llm-api-reference.md

@@ -0,0 +1,5 @@
+---
+"@feltmaps/js-sdk": patch
+---
+
+Ship `llms-full.txt`, a single-file API reference for LLM consumption, in the package. It is generated from the TypeScript definitions on every build.

CLAUDE.md

@@ -5,11 +5,24 @@ Public JS SDK for embedding and controlling Felt maps. Two entry points: `client
 ## Commands
 
 - `npm run check` — full validation (bundle, format, API, types, tests, docs)
-- `npm run build` — compile + generate docs
+- `npm run build` — compile + generate `docs/` and `llms-full.txt` (commit both; `npm run check` fails on drift)
 - `npm run update-api` — regenerate `etc/js-sdk.api.md` after API changes (stage before `npm run check`)
 
 ## Key constraints
 
 - Every change needs a changeset (`npm run changeset`).
 - Never edit `version` in `package.json` by hand; the release flow (`changeset version`) owns it and syncs `package-lock.json`. If `npm run check:lockfile` fails, run `npm install --package-lock-only`.
 - See `DEVELOPING.md` for module structure and `RELEASING.md` for the branching/release model.
+
+## TSDoc conventions
+
+`llms-full.txt` is generated from the TSDoc and is what AI agents read when using the SDK, so the
+comment on every exported type, property and method is part of the public API.
+
+- Summary: one sentence. Only the first sentence is rendered.
+- `@defaultValue` for defaults. Rendered as `default: ...`; not rendered for `undefined`.
+- `@remarks` for anything an agent needs that the types don't show: what each enum value means,
+  pagination rules, caveats, which methods a value can be passed to. Rendered in full; bulleted and
+  numbered lists keep their lines.
+- `@example` is only rendered in the TypeDoc site, not in `llms-full.txt`, so don't rely on examples
+  to carry information that isn't also in the summary or `@remarks`.

DEVELOPING.md

@@ -70,6 +70,12 @@ Once you have added your module:
 
 1. Run `npm run build` to ensure everything compiles and the docs are generated. It's possible for the docs to
    fail to build if some types are not exported, but you will be warned in the console about this.
+   This also regenerates `llms-full.txt`, a single-file API reference for LLM consumption that ships in
+   the npm package and is used by the Felt app as agent context. It is derived from the TypeScript
+   definitions and TSDoc; the first sentence of each summary, `@defaultValue` and the full text of
+   `@remarks` are rendered there (`@example` blocks are not), so keep summaries to one sentence, put
+   defaults in `@defaultValue`, and put anything an agent needs that the types don't show under
+   `@remarks`.
 2. Run `npm run update-api` to run api-extractor which updates the "api spec" file, which allows
    reviewers to understand the changes made to the API.
 3. Stage or commit your changes. This is important, because the next step will fail if you have
@@ -86,6 +92,7 @@ There are various checks in the `check` script to ensure that:
 - the bundle is correctly built with the correct types
 - everything is used (i.e. you didn't forget to add your module to the main module list)
 - the docs build and all necessary types are included
+- the committed `docs/` and `llms-full.txt` output matches what the build generates
 - `zod` isn't accidentally included in the client bundle
 - the `handler` correctly receives every message that the client can send