feat(docs): document embedded-API entity types as an APIModels reference

[mariechatfield]

Summary

Documents the @gusto/embedded-api entity types in the SDK reference. Previously every hook/component that returned a raw embedded-API type (Form, Employee, Compensation, …) rendered it as bare, unlinked text in the generated tables, because those types live outside TypeDoc's entry point.

• Re-export the referenced models/components/* entity types through a generated barrel (src/models/external.ts), surfaced as the APIModels namespace from src/index.ts, so TypeDoc documents their full shapes and every reference becomes a link.
• Generator (build/deriveExternalModels.ts, wired in via models:derive / models:verify):
  • version-agnostic (reads the dated package + repo + version from the package's own package.json)
  • auto-detects value-enums vs type-only re-exports
  • backfills a TSDoc summary for entities the upstream package doesn't document (otherwise excludeNotDocumented silently drops them)
  • follows transitive type references (same-file siblings + ./<module> imports) so sub-types like DepartmentEmployees, Job, MinimumWages are documented and linked instead of rendering bare
  • formats its output with the repo's Prettier config so the auto-derived file passes format:check
• Rewrites {@link Entity} prose refs to {@link APIModels.Entity}.
• Each entity's "Defined in" links to gusto-typescript-client at the installed version tag (e.g. …/blob/gusto_embedded_v_2025_11_15/v0.0.2/…#L11), with the correct source line.
• Sidebar: APIModels is pinned to the end as "API Models" (its own group, not under "Namespaces").
• CI: a dedicated derive-models job single-sources the barrel; build (→ API report) and derive-check-src (→ docs) both consume that one artifact, so external.ts + docs + report regenerate consistently in one derive-commit.

Distributed size impact

Does the barrel bloat the published package / pull every model in via tree-shaking?

No runtime impact. The namespace is exported type-only (export type * as APIModels), so it is fully erased from the JS bundle.

	main (before)	this branch (after)	Δ
Runtime JS (dist/**/*.js)	2082.2 KB	2082.2 KB	0
Type declarations (dist/**/*.d.ts)	~1316.8 KB	1346.5 KB	+29.7 KB

Why there's no runtime cost or tree-shaking hazard:

• No external.js chunk is emitted, and APIModels appears in zero dist JS files — the type-only namespace re-export is stripped by the TS transform before bundling.
• dist/models/external.d.ts is 29.7 KB of re-export lines only — zero inlined type bodies. The actual model definitions stay in @gusto/embedded-api (already a dependency); they are not copied into our dist.
• Tree-shaking is moot: there is no runtime code to shake. A consumer that references APIModels.Employee pulls only the type into their type-check — nothing into their bundle. The value-enums the barrel re-exports (GarnishmentType, etc.) are reached at runtime only via their existing direct imports in components, never via this barrel.

So the entire footprint of this feature on the published artifact is ~30 KB of additional .d.ts re-export lines, and 0 bytes of runtime JS.

Generated output

docs/reference/** and .reports/*.md are intentionally not committed here — CI's derive step regenerates and commits them (it already has on this branch). src/models/external.ts is committed because it is part of the compile graph.

🤖 Generated with Claude Code