docs(mentions): specify portable mention rules

[loganj]

🤖
Replaces #270, which GitHub could not reopen after its base branch (#258) merged.

Summary

• Other Buzz clients need a precise way to give the same mention list and send the same tags as this app. This PR writes the mention rules of the merged chooser (Ask before mentioning people outside the channel #257, Make mention choices consistent and stable #258, and the related rules from feat(profiles): archive, unarchive and delete agents from the profile pane #256 and fix: retire mention searches after chips and refuted prose #303) as a client-independent spec. It adds shared input and output examples ("fixtures") that any client can use to check its implementation.
• It does not change how the app behaves.

What the spec covers

• Who you can mention: channel members, the agents offered in the channel, and, in channels and forums only, people found in the community directory. Archived people are left out, but you always see yourself.
• How @ text is read: when completion opens, when a query with a space is still part of a name, and when it is prose. Prose closes the list and starts no search.
• Matching and order: members first, then better matches, then your own agents, then names. Agents with the same name stay together in one group, ordered by your recent choices, managed agents, and presence. The order is the same for any input order.
• Space: when Space completes a mention.
• List stability: rows do not move while the list is open, and searches that find no one are not kept. This is desktop behavior and the fixtures do not test it.
• People outside the channel: the send prompt with Do nothing / Invite, or Send anyway. It follows the block/buzz desktop dialog, and the spec names that source file.
• Tags: a p tag notifies a person (a recipient). A two-field mention tag names a person without notifying them (a reference). This is the same format that other Buzz clients already write. No new event kind or NIP.
• It also says what a mention does not do: choosing a person does not give them access, and it does not promise that an agent will answer.

Details

• The spec is in src/bundled/mentions/README.md, next to the plugin that implements the chooser. This is the same layout as the identity-naming spec (docs(names): specify portable identity disambiguation #227). The README links to it.
• mention-rules.fixtures.json has 69 cases: ranking (26), Space (12), query syntax (12), multi-word queries (6), tag writing (7), and tag reading (6). The expected outputs are written by hand. The code under test does not generate them.
• The app's existing test files run every case through the production code: the ranking and Space functions, the @ query parser, the message send path, and the message reader. No existing test changed.

[wesbillman]

Star Lord automated source review (via Wes’s account)

Reviewed head 5605f7bfd4b27dc11604532910f415a02d4cd7d9 against base 1d19153276b93ef733fe5e8ead888fc528fc00e3.

One actionable P2 contract mismatch, detailed inline: section 2 turns a local name-admission predicate into a prohibition on directory discovery, contrary to the existing desktop behavior and its explicit regression test. This is a documentation/portability defect; this PR does not change production behavior.

Source scope: all eight changed files; the 69 literal fixtures and their adapters; production ranking/Space selection, query admission and directory lifetime, choice eligibility/naming, outside-member consent, and recipient/reference writing and folding. Checked the relative spec links and pinned upstream tag/dialog precedents. No other actionable findings in this scope.

Validation limits: source inspection only. I did not execute PR code, fixtures, tests, builds, installs, or app workflows, and did not inspect CI in this cycle. Existing test assertions cited below are source evidence, not a reported test pass. Human confirmation and cross-client/runtime conformance remain unverified. This is a nonblocking COMMENT review, not approval or merge authorization.

[wesbillman]

Star Lord automated source review (via Wes’s account)

Follow-up review of head 019b847052d2a13d570336727585a34fef333a65 against base 1d19153276b93ef733fe5e8ead888fc528fc00e3; change since my prior review: 5605f7bfd4b27dc11604532910f415a02d4cd7d9..019b847052d2a13d570336727585a34fef333a65.

The prior P2 is resolved. No new actionable findings in this follow-up. Section 2 now separates multi-word name admission from directory discovery, preserves the error/retry path, and rechecks admission against discovered names. This matches MentionCompletion.tsx:64–90, use-mention-choices.ts:54–60, and the existing “a failed multi-word directory search keeps its error and retry” test at session-agents.test.tsx:1552–1571. Section 6 also documents the refuted-prefix search optimization and exact-key lookup exception.

Scope: the README-only repair, its interaction with sections 1 and 6, query admission, directory search/cache/refutation lifecycle, and the relevant existing regression-test source. The remaining PR inputs are unchanged from the prior review; pinned blob/content hashes and the README’s relative links were checked. This is a follow-up on the earlier finding, not a new review of unrelated areas.

Validation limits: source inspection only. No PR code, fixtures, tests, builds, installs, or app workflows were executed; CI was not checked in this cycle. Test references describe assertions in source, not reported passes. Human confirmation and cross-client/runtime conformance remain unverified. This is a nonblocking COMMENT review, not approval or merge authorization.