[karl-bullock]

Findings from reading extend/api.md and extend/update-2_0-api.md against the source claim by claim, rather than checking that the symbols exist. Two of these are real bugs; the rest are small things found in the same passes.

Three localhost:3000 links are published

extend/forms.md and extend/update-2_0-api.md (twice) link to http://localhost:3000, which is somebody's local Docusaurus dev server. They are broken for every reader of the site. All three now point at the pages they meant, relatively:

• forms.md to admin.md#registering-settings
• update-2_0-api.md, both occurrences, to api.md#relationship-aggregates

The relationship linkage claim is backwards

api.md said:

(ToMany relationships are not linked by default contrary to ToOne relationships)

That tells the reader a ToOne relationship's identifier appears in the payload without asking for it. It does not. Linkage is declared once, on the shared Relationship base class:

public bool|Closure $linkage = false;

Neither ToOne nor ToMany overrides it, and both serialize through the same hasLinkage($context) check. The only withLinkage() call anywhere in core or the bundled extensions is on a ToMany relationship (posts on DiscussionResource), which is the opposite of what the sentence implies.

The replacement says neither carries linkage by default and that withLinkage is how you opt in, and keeps the useful part the original was reaching for by noting that a relationship actually included in a response carries its identifiers regardless. The performance caution about ToMany linkage immediately below it is correct and untouched.

Checked against flarum/json-api-server 0.1.2, which is the highest release in the 0.1.x line that core's ^0.1.0 resolves to, so it is what a 2.0 install actually gets.

Smaller things in the same pages

• Three absolute https://docs.flarum.org/2.x/... self-links in update-2_0-api.md, and one https://docs.flarum.org/mail in admin.md, are now relative. They did resolve, but only via a redirect hop, and an absolute link is invisible to the build's link checker, so it cannot be caught if a page moves. Relative links are checked at build time and work in a local build and in previews.
• A stray backtick terminated a code sample mid-line in update-2_0-api.md, leaving an orphaned second code block immediately after it with no text between the two. The backtick is gone and the two samples are merged into one, with a comment separating them.
• "which can be re-used inn different places" now reads "in".

What I checked and did not need to change

Worth recording, so the same ground is not covered twice:

• Every method name used in a code block on both pages was checked against every method defined in flarum/framework@2.x plus the json-api-server vendor package. Everything resolves. The names that initially looked missing were PSR-7 and Eloquent methods, the scopeWhereVisibleTo Eloquent scope, or third-party fof/gamification and fof/drafts code deliberately shown as the 1.x "before".
• paginate(20, 50) matches the real defaults (paginate(int $defaultLimit = 20, int $maxLimit = 50)), and its inline comment is accurate.
• The claim that "in 2.x, the show discussion endpoint no longer tries to load the posts relation models" is correct: DiscussionResource's Show endpoint lists firstPost and lastPost in defaultInclude and not posts.
• countRelation and sumRelation exist with the documented signatures.
• extensions/audit.md was checked separately: both documented permissions and all ten documented action names exist in the extension's source.