docs: bring every package's AI.md back in line with what it publishes - #33
Merged
Merged
Conversation
The shipped AI.md files had gone stale in the way generated-and-committed docs always do: silently, and only for the audience that cannot file an issue about it. CI regenerates llms.txt and diffs it, which catches a stale bundle — but a stale *source* regenerates perfectly, so an AI.md that never mentions the subpath a release added stays wrong forever. What had drifted: - `@amritk/mini` documented neither `watch` nor `template`, nor the typed `matchRoute` / `buildPath` re-exports on `/router`, nor `Field` on `/forms`, nor the `/vite` subpath at all. - `@amritk/mini-lynx` was missing `computed` / `effectScope`, `fadeTransition`, `keepAboveKeyboard` / `focusedField` and `HANDLER_PREFIX`. - `@amritk/lynx-notifications` documented neither its `/testing` subpath nor the fake behind it, and had no Status section. - All four native packages exported `MODULE` and `EVENTS` with nothing saying what they are for, and only `lynx-dialogs` showed how to wire a fake into `installNativeBridge` — the one thing a consumer testing its own screens needs. Two accuracy fixes matter more than the additions. Every native package's Status section claimed the Objective-C compiles against the real Lynx pod; the macOS job was disabled on cost, so it now compiles only when somebody runs `pod lib lint` by hand, and the docs say so. And `lynx-dialogs` carried no Status section at all, so nothing in it told a reader that none of it has run on a device. `bun run check:ai-docs` is the guard: it reads each package's `exports` and fails on a runtime export, a published subpath, or (for a package shipping native sources) a Status section the AI.md never mentions. It runs early in CI, before the build, because it needs neither. Exports no consumer ever writes — the tree operations the JSX transform calls, and the like — are listed in INTERNAL_EXPORTS with the reason, so a new export cannot join them by accident. Types are deliberately out of scope: an AI.md documents shapes by writing them out, and requiring the identifier would push these files toward being a second copy of the .d.ts, which is the one thing they must not become. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The shipped AI.md files had gone stale in the way generated-and-committed
docs always do: silently, and only for the audience that cannot file an
issue about it. CI regenerates llms.txt and diffs it, which catches a stale
bundle — but a stale source regenerates perfectly, so an AI.md that never
mentions the subpath a release added stays wrong forever.
What had drifted:
@amritk/minidocumented neitherwatchnortemplate, nor the typedmatchRoute/buildPathre-exports on/router, norFieldon/forms, nor the/vitesubpath at all.@amritk/mini-lynxwas missingcomputed/effectScope,fadeTransition,keepAboveKeyboard/focusedFieldandHANDLER_PREFIX.@amritk/lynx-notificationsdocumented neither its/testingsubpath northe fake behind it, and had no Status section.
MODULEandEVENTSwith nothingsaying what they are for, and only
lynx-dialogsshowed how to wire afake into
installNativeBridge— the one thing a consumer testing its ownscreens needs.
Two accuracy fixes matter more than the additions. Every native package's
Status section claimed the Objective-C compiles against the real Lynx pod;
the macOS job was disabled on cost, so it now compiles only when somebody
runs
pod lib lintby hand, and the docs say so. Andlynx-dialogscarriedno Status section at all, so nothing in it told a reader that none of it has
run on a device.
bun run check:ai-docsis the guard: it reads each package'sexportsandfails on a runtime export, a published subpath, or (for a package shipping
native sources) a Status section the AI.md never mentions. It runs early in
CI, before the build, because it needs neither. Exports no consumer ever
writes — the tree operations the JSX transform calls, and the like — are
listed in INTERNAL_EXPORTS with the reason, so a new export cannot join them
by accident.
Types are deliberately out of scope: an AI.md documents shapes by writing
them out, and requiring the identifier would push these files toward being a
second copy of the .d.ts, which is the one thing they must not become.
Co-Authored-By: Claude Opus 5 noreply@anthropic.com
📦 Bundle-size delta vs main (
5ce0ea4→530d7d6)Gzipped bytes of each bundled entry (esbuild, minified, browser/es2022, optional peer deps external). Bundling is deterministic, so unlike a timed benchmark these numbers carry no noise and every Δ is exact. ⚪ within ±0.5% · 🟢 smaller · 🔴 larger. Each package's
core (.)must stay flat as subpath features land — that is the whole charter, andsrc/core-size-budget.test.tsholds the absolute ceiling.