docs: restructure usage examples and add context7 configuration#86
Merged
Merged
Conversation
Restructure the README usage section into task-oriented headings so each example is self-contained: full request lines for locale selection, a response example for ?groups[]=translations, a merge patch example (the recommended way to edit translations, previously the only edit example showed the PUT payload), and an explicit full-replace PUT section. Add a limitations section covering the two known gaps (no filtering by translated fields, one translation query per collection item) and normalize code fence info strings. Add context7.json so the Context7 documentation index used by AI coding agents serves curated content: README, changelog and upgrade guides only, usage rules stating the bundle's conventions and footguns, versioned docs for the 1.4 and 2.0 tags, and the verification key linking the index entry to this repository.
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.
Problem
The README's usage examples sit under a single vague "Usage" heading as bold pseudo-headings, which reads fine on GitHub but retrieves poorly in documentation indexes such as Context7 that serve snippets to AI coding agents by nearest heading. PATCH is the recommended way to edit translations but the only edit example showed the PUT payload with ids, there was no response example for
?groups[]=translations, and known limitations (filtering by translated fields, the per-item translation query on collections) were undocumented, which leads agents to invent answers instead of stating they are not supported. The bundle is also not yet indexed on Context7, so agents answer questions about it from stale training data.Changes
Accept-Languageas full request lines), return all translations (now with a response example showing the group is additive), create with POST, update with PATCH, replace with PUT.standard_putnotes.EXTRA_LAZY, no built-in eager loading).``` phpto```php).context7.json, validated against the published schema: indexes only README, changelog and upgrade guides (excludessrc,tests,config,bin), eleven usage rules covering the conventions and footguns (serialization groups, payload shape, PATCH over PUT,standard_put, locale selection), versioned docs for thev2.0.1andv1.4.1tags, and the ownership verification keys for the Context7 entry.