[karl-bullock]

Both code samples under Example Policies are 1.x code presented as current Flarum Tags source, and the page links to that source, so a reader who follows the link finds something quite different from what they were just shown.

GlobalPolicy: the sample would not run

count(Tag::getIdsWhereCan($actor, $ability, true, false)) >= $this->settings->get('min_primary_tags')

Tag::getIdsWhereCan() does not exist anywhere in 2.x, and the setting keys lost their namespace at some point (flarum-tags.min_primary_tags now). So this is not merely dated: copying it produces a fatal.

It is replaced with a simplified policy assembled from real APIs, a ?string return, the namespaced setting, and the Tag::whereHasPermission scope. I have not pretended the real implementation is that short: a note says it is simplified, and that the real one also handles secondary tags, short-circuits on bypassTagCounts, memoizes its verdict per actor and ability, and counts both tag kinds in one aggregate query, which matters because a global policy runs on a great many requests.

TagPolicy: the sample misses the two things worth learning from it

The old sample defines one method per ability (startDiscussion, then addToDiscussion delegating to it) and wraps hasPermission in a ternary. The real one does neither:

• It uses the can() catch-all, so a single method serves every ability. The page already explains that mechanism a few paragraphs earlier, and this is the example that should demonstrate it.
• It returns the result of hasPermission directly, because AbstractPolicy::sanitizeResult converts true and false into allow() and deny(). The ternary is noise.
• It also inherits restrictions from a parent tag, which is a real behaviour of the extension that the sample silently dropped.

The sample now matches the real class, and the prose points out those two habits rather than leaving the reader to notice them.

Note on overlap

The introductory line above the first sample is deliberately untouched, because #592 corrects the branch in its link (blob/master to blob/2.x). That matters here: once that link points at 2.x, the mismatch between the page and the linked source becomes obvious, which is how I found this. I verified this branch and #592 merge cleanly.

Verified with npx docusaurus build --locale en: no errors, and no anchors broken by this change (the two the build reports on these pages are pre-existing and fixed by #592).