Skip to content

docs: bring every package's AI.md back in line with what it publishes - #33

Merged
amritk merged 1 commit into
mainfrom
claude/optimized-ai-files-packages-qyt8cq
Aug 5, 2026
Merged

docs: bring every package's AI.md back in line with what it publishes#33
amritk merged 1 commit into
mainfrom
claude/optimized-ai-files-packages-qyt8cq

Conversation

@amritk

@amritk amritk commented Aug 5, 2026

Copy link
Copy Markdown
Owner

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

📦 Bundle-size delta vs main (5ce0ea4530d7d6)

Package Entry main PR Δ
mini core (.) 3,156 B 3,156 B +0 B (+0.0%) ⚪
mini flow 4,083 B 4,083 B +0 B (+0.0%) ⚪
mini router 4,259 B 4,259 B +0 B (+0.0%) ⚪
mini forms 4,259 B 4,259 B +0 B (+0.0%) ⚪
mini query 1,988 B 1,988 B +0 B (+0.0%) ⚪
mini-lynx core (.) 5,605 B 5,605 B +0 B (+0.0%) ⚪
mini-lynx flow 4,981 B 4,981 B +0 B (+0.0%) ⚪
mini-lynx router 6,130 B 6,130 B +0 B (+0.0%) ⚪
mini-lynx forms 5,400 B 5,400 B +0 B (+0.0%) ⚪
mini-lynx query 1,990 B 1,990 B +0 B (+0.0%) ⚪
mini-lynx testing 2,464 B 2,464 B +0 B (+0.0%) ⚪

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, and src/core-size-budget.test.ts holds the absolute ceiling.

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>
@amritk
amritk merged commit 8729b44 into main Aug 5, 2026
3 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants