Give an example an apis field, and take the notes away - #208
Closed
abernier wants to merge 1 commit into
Closed
Conversation
The document an agent reads names no technique. `aquarium` is served with an empty description and the single tag `transmission`, while what makes it work -- `useMask` and a backside `MeshTransmissionMaterial` -- is nowhere, and the reader pays 400 lines of TSX to rediscover it. Identifiers are data, not prose. Three median-length API names are 34 characters, 28% of the 120 the one-line `description` gets, which is exactly why they get their own field rather than eating the sentence. `apis` renders in the facts block of `<name>.md`, next to the tags, and not in `llms.txt`: ~34 characters on 167 index lines takes that file from ~19 kB to ~25 kB, on a document read at the start of every question, to say what is one fetch away once the choice is already made. Optional for now. It becomes required once every example carries one -- required before it is populated is a red CI on day one. `lint:metadata` enforces `apis ⊆ imports`, as a hard error. The check is local and only local: whether drei still exports the name at the pinned version is the bundler's job, and rollup already fails the build on a missing named export. What no build can catch is metadata drifting away from the source, and that is what this catches -- drei renames an API, someone fixes the import, `apis` still lists the old name, the lint breaks. That property is why the example's sources are now inputs of `//#lint:metadata`: cached past a dropped import, the rule stops catching the one thing it exists for. `notes` goes. Two uses, both the same string, "Updated for MeshTransmissionMaterial in 2023." -- maintenance history that belongs in git, rendered into the document where a reader cannot tell it from documentation. `assets[].notes` had zero uses and went with it. Closes #194
This was referenced Aug 14, 2026
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 document an agent reads names no technique.
aquariumis served withan empty description and the single tag
transmission, while what makesit work --
useMaskand a backsideMeshTransmissionMaterial-- isnowhere, and the reader pays 400 lines of TSX to rediscover it.
Identifiers are data, not prose. Three median-length API names are 34
characters, 28% of the 120 the one-line
descriptiongets, which isexactly why they get their own field rather than eating the sentence.
apisrenders in the facts block of<name>.md, next to the tags, andnot in
llms.txt: ~34 characters on 167 index lines takes that file from~19 kB to ~25 kB, on a document read at the start of every question, to
say what is one fetch away once the choice is already made.
Optional for now. It becomes required once every example carries one --
required before it is populated is a red CI on day one.
lint:metadataenforcesapis ⊆ imports, as a hard error. The check islocal and only local: whether drei still exports the name at the pinned
version is the bundler's job, and rollup already fails the build on a
missing named export. What no build can catch is metadata drifting away
from the source, and that is what this catches -- drei renames an API,
someone fixes the import,
apisstill lists the old name, the lintbreaks. That property is why the example's sources are now inputs of
//#lint:metadata: cached past a dropped import, the rule stops catchingthe one thing it exists for.
notesgoes. Two uses, both the same string, "Updated forMeshTransmissionMaterial in 2023." -- maintenance history that belongs in
git, rendered into the document where a reader cannot tell it from
documentation.
assets[].noteshad zero uses and went with it.Closes #194
Stack created with GitHub Stacks CLI • Give Feedback 💬