Enrich public-api.json with per-symbol usage notes and gotchas (follow-up to #27)

[mkotulac-markot]

Problem

#27 shipped packages/core/dist/public-api.json as a drift-guard manifest — a names-only list of exports. GPT's alpha.7 feedback asks for a machine-readable API export that also includes short usage notes and gotchas per symbol, which is a distinct artefact: something an LLM-facing tool (or a pre-commit agent for AI-generated code) can consume to check not just "does bindPath exist" but "what's its shape and what are its common misuse patterns". This is the infrastructure version of the LLM reference card.

Evidence

• GPT (under "What would most improve AI-assisted development"): "A machine-readable API export that also includes short usage notes and gotchas per symbol."

Claude did not raise this as a friction point. Single-reviewer, infrastructure work, clear deliverable → P3 polish.

Options

A — Enrich the existing public-api.json

Extend each export from a bare string to an object: { name, kind, signature, summary, gotchas[], since, seeAlso[] }. Populate from a source-of-truth table (probably a new packages/core/src/api-metadata.ts that the LLM reference is already generated from).

• Pros: single manifest, stable URL, both the drift-guard and LLM-consumption use cases share the same file. The LLM reference card can itself be regenerated from it.
• Cons: api-metadata.ts becomes a bigger surface to keep in sync than the current names-only list. Every new export now needs a metadata entry, not just an index addition.

B — Ship a second file public-api-annotated.json

Keep public-api.json as names-only (for drift-guard), add a richer sibling.

• Pros: zero risk to existing drift-guard tooling.
• Cons: two sources of truth for the export list. If they drift (one updated, the other missed), the value of the annotated one collapses.

C — Don't ship the artefact; expand the LLM reference card

The LLM reference card at docs/reference/for-llms.md on whisq.dev already contains much of what GPT is asking for, just in markdown form. Teach tools to consume that file instead.

• Pros: nothing new to build.
• Cons: markdown is hard to parse reliably; every consumer has to re-parse. The whole point of a machine-readable artefact is to skip that.

Recommendation

A, but gated behind two release cycles of real-world usage. The LLM reference is currently hand-curated (#79's output); before wiring generator tooling the team should be confident the reference's shape is stable. Meanwhile, spec the JSON schema of the enriched manifest so consumers can build against it, and close with a concrete consumer need (e.g., a pre-commit check or the MCP server at packages/mcp-server/) rather than speculatively shipping a manifest with no consumer.

Acceptance criteria

• Written JSON-schema-style spec for the enriched manifest shape, committed under packages/core/docs/api-metadata-schema.md.
• At least one concrete consumer identified and linked in the spec (most likely: extend @whisq/mcp-server to serve per-symbol gotchas, since it already consumes the names-only manifest).
• Generator: a script that reads api-metadata.ts + TSDoc from source and emits the enriched manifest during build.
• CI check: enriched manifest must include every name from the existing names-only manifest (no drift between the two).
• Changeset documents the new consumer contract.

Context

Source: dev/feedback/latest/FRAMEWORK_FEEDBACK_GPT_v0.1.0-alpha.7.md "What would most improve AI-assisted development" #3. Related: #27 (current names-only manifest), packages/mcp-server/ (likely consumer).

[mkotulac-markot]

Filed a concrete first-PR spike as #138 — the umbrella issue's 'identify a concrete consumer' AC turned out to be non-trivial on inspection: packages/mcp-server/src/tools/api-docs.ts today serves hand-written markdown per topic and doesn't consume public-api.json at all. The spike carves out the minimum evidence of value (schema + generator + one migrated MCP topic) sized for a single /full-feature run. If the shape holds, the remaining topics + CI drift check become mechanical follow-ups against this umbrella.

[mkotulac-markot]

Status after #138 landed — 4 of 5 ACs are done; the remaining one is the scope blocker:

• ✅ JSON-schema spec — packages/core/docs/api-metadata-schema.md
• ✅ Concrete consumer identified and linked — @whisq/mcp-server signals topic consumes @whisq/core/public-api-annotated.json
• ✅ Generator script — packages/core/scripts/generate-api-metadata.mjs, wired into pnpm build with drift guards
• ❌ CI check: enriched manifest includes every name from names-only manifest. Currently 4 of 107 exports enriched. This AC can't pass until the remaining ~103 symbols have metadata.
• ✅ Changeset documents consumer contract — shipped with Spike: spec enriched public-api.json schema + migrate one MCP topic as proof #138

Why this stays open

The fourth AC is content work, not engineering. Each remaining symbol needs a curated summary, signature, gotchas, examples, and seeAlso entry. The generator + drift guards are in place; what's missing is filling the metadata table.

Proposed slice strategy

Rather than one big content-curation PR or 100+ tiny issues, carve by topic (same groupings as @whisq/mcp-server's ApiTopic enum). Each slice is one /full-feature-sized unit: enrich the curated JSON for that topic and migrate the corresponding MCP DOCS.<topic> entry.

Remaining slices (rough symbol counts against public-api.json):

• elements — div, span, h1–h6, p, a, button, form, label, input, …, plus h, raw, when, match, each, errorBoundary, portal, transition, mount (~40 symbols)
• components — component, onMount, onCleanup, resource, createContext, provide, inject (~7 symbols)
• styling — sheet, styles, cx, rcx, sx, theme + types (~8 symbols)
• forms — bind, bindField, bindPath, compose + types (~10 symbols)
• signals-support — remaining reactive support types (Signal, ReadonlySignal, event-handler types) (~5 symbols)
• persistence / ids / collections — sub-path topics: persistedSignal, createStorageNamespace, randomId, signalMap, signalSet, partition (~10 symbols incl. types)
• dev-errors — WhisqStructureError, WhisqKeyByError (~3 symbols)
• sub-path stubs — partition/signalMap/signalSet/randomId/persistedSignal/bindPath main-entry stubs; could be one entry per stub pointing at the real sub-path symbol (~6 symbols)

Each slice ends with a tightened MCP regression test (same shape as the signals one added in #138). When all topics are covered, a final PR turns on the AC-4 CI drift check — "every public-api.json export must have an enrichment entry" — and #103 closes.

Happy to file the next one as a concrete elements-topic issue when someone wants to pick it up, or to fold multiple into one /full-feature run if the content feels similar enough to bundle.