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

.changeset/ai-docs-audit.md

@@ -0,0 +1,36 @@
+---
+'@amritk/lynx-deep-linking': patch
+'@amritk/lynx-notifications': patch
+'@amritk/lynx-dialogs': patch
+'@amritk/lynx-location': patch
+'@amritk/mini-lynx': patch
+'@amritk/mini': patch
+---
+
+Bring every package's shipped `AI.md` back in line with what that package
+actually publishes, and add `bun run check:ai-docs` so it cannot drift again.
+
+The 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.
+`@amritk/mini` never documented `watch`, `template`, the typed `matchRoute` /
+`buildPath` re-exports on `/router`, `Field` on `/forms`, or the `/vite` subpath
+at all; `@amritk/mini-lynx` was missing `computed` / `effectScope`,
+`fadeTransition`, `keepAboveKeyboard` and `HANDLER_PREFIX`;
+`@amritk/lynx-notifications` documented neither its `/testing` subpath nor the
+fake behind it. All four native packages exported `MODULE` and `EVENTS` with no
+mention of what they are for, and only `@amritk/lynx-dialogs` showed how to wire
+a fake into `installNativeBridge` — which is 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 CI job was disabled on cost, so it now compiles only when somebody runs
+`pod lib lint` by hand, and the docs say that. And `@amritk/lynx-dialogs` never
+carried a *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` reads each package's `exports` and fails on a runtime
+export, a published subpath, or (for a package shipping native sources) a
+*Status* section its `AI.md` never mentions. It runs early in CI, before the
+build. Exports no consumer ever writes — the tree operations the JSX transform
+calls, and the like — are listed in `INTERNAL_EXPORTS` with the reason.

.github/workflows/ci.yml

@@ -27,6 +27,13 @@ jobs:
       - name: Check mini reactivity footgun
         run: bun run check:reactivity
 
+      # Regenerating `llms.txt` catches a stale bundle, but a stale *source*
+      # regenerates perfectly: an `AI.md` that never mentions the subpath a
+      # release added is wrong in a way no diff can see. This reads what each
+      # package actually exports and asks whether its `AI.md` says so.
+      - name: Check AI docs match what each package publishes
+        run: bun run check:ai-docs
+
       # `llms.txt` and `llms-full.txt` are generated from the packages' `AI.md`
       # files and committed, so they go stale in exactly the way a committed
       # build artifact always does: silently, and only for the audience that

AGENTS.md

@@ -15,6 +15,15 @@ this repository**. For Claude Code the same rules live in
 > an **`AI.md`** next to its `README.md` with a mental model, a minimal example,
 > and the gotchas most likely to trip up an LLM. Start there.
 
+**Adding an export means adding a line to that package's `AI.md`.**
+`bun run check:ai-docs` reads what each package publishes and fails on anything
+its `AI.md` never mentions — a new subpath, a new function, a native package
+with no *Status* section. It is not a style check: these files are the only
+documentation a coding agent consuming the package will ever read, and a wrong
+one is worse than a missing one because nothing about it looks stale. An export
+no consumer ever writes goes in `INTERNAL_EXPORTS` in `scripts/ai-docs.ts`, with
+the reason.
+
 ## What this is
 
 `mini` is a **Bun monorepo** holding a deliberately tiny signals UI runtime in
@@ -86,6 +95,7 @@ bun install                 # install workspace deps
 bun run test                # run every package's tests (packages/* only)
 bun run check               # biome lint + format check
 bun run check:reactivity    # guard the compilerless-JSX called-signal footgun (packages + apps)
+bun run check:ai-docs       # every package's AI.md against what that package actually exports
 bun run check:android       # compile the notifications Kotlin (needs ANDROID_HOME; skips without)
 bun run types:check         # type-check both packages and both playgrounds
 bun run build               # build both packages and both playgrounds

CONTRIBUTING.md

@@ -20,6 +20,7 @@ You'll need [Bun](https://bun.sh) ≥ 1.1.
 | `bun run check` | Lint with biome |
 | `bun run format` | Auto-format with biome |
 | `bun run check:reactivity` | Catch signals frozen by being called in JSX |
+| `bun run check:ai-docs` | Check every package's `AI.md` against what it publishes |
 | `bun run types:check` | Type-check both packages and both playgrounds |
 | `bun run build` | Build both packages and both playgrounds |
 | `bun run test:dist` | Load, drive and npm-install the built artifacts (needs a prior build) |