docs: add agent glossary and AGENTS.md - #1077
Draft
yattias wants to merge 1 commit into
Draft
Conversation
Adds docs/glossary.md, a reference for the domain and architecture vocabulary an agent needs to work in this repo: the content model (Work, unified documents, the ContentType/ApiDocumentType split), the funding flow (RFP, proposal/preregistration, fundraise, registered report), RSC and dual-currency amounts, bounties, tips and comment-backed reviews, the notebook, feeds, the ApiClient and transformer layers, and the UI/state conventions. Each entry names the file that defines the term, and a final section lists the identifiers that are reused with different meanings across modules. Adds AGENTS.md pointing at the glossary and covering commands, repo layout, and the conventions that are easy to get wrong. lint-staged runs eslint and tsc, neither of which applies to markdown, and node_modules cannot be installed here without the private registry credentials, so this commit skips the hook. Formatting was verified with prettier directly.
Contributor
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
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
2 participants
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.
What
Two new docs aimed at AI coding agents (and new engineers):
docs/glossary.md— the domain and architecture vocabulary of this repo, grouped by area, with the defining file named for every entry.AGENTS.md— a short orientation doc that links the glossary and covers commands, repo layout, and the conventions that are easy to get wrong.Why
A lot of this codebase's vocabulary does not mean what it sounds like, and the mismatches are the kind that produce quietly wrong code:
preregistrationin the data model, and an RFP is aGrantwithcontentType: 'funding_request'.ContentType,DocumentType,CommentType,Contribution,Author,useComments, andtransformUnifiedDocumenteach mean different things in different modules.purchases, and calls topicshubs.rscUsdSnapshotrather than the live exchange rate.The glossary closes with an "Ambiguous names" section listing every collision found, since those are the ones most likely to cause a bad edit.
AGENTS.mdalso records a few facts that are not discoverable from the code alone:npm installneeds an.npmrcwith Tiptap Pro and FontAwesome Pro credentials, CI gates only the smoke suite (not lint, type-check, or build), and a long list of stock ESLint rules is disabled — so a cleannpm run lintdoes not imply idiomatic code.Scope
Documentation only. No source files are touched.
Verification
Every claim was read out of the source rather than inferred. Two scripted checks back that up:
BaseService,fetchWithAuth, a lowercaseapiClient) were asserted absent.Both docs are Prettier-clean, matching the rest of the repo's markdown.
npm run type-checkandnpm run lintcould not run in this environment becausenpm installfails without the private registry credentials, and neither applies to markdown. The pre-commit hook was skipped for the same reason.