Enhance pragmatics documentation with new sections and examples

[Bananamilk452]

Close #946

This pull request adds comprehensive documentation to pragmatics.md on audience addressing, replies, quote policies, and microformats in ActivityPub objects. The new sections clarify how to use the to/cc properties, create replies with proper audience and mentions, implement consent-respecting quote policies, and ensure interoperability with Mastodon and other platforms through microformats.

Audience addressing:

• Added a section describing the use of to and cc properties (and their plural forms) for specifying primary and secondary recipients on ActivityPub objects, including code examples and links to further documentation.

Replying and quoting:

• Documented how to create replies with Note.replyTarget, proper audience (to, ccs), and Mention tags, including a detailed code example. Explained requirements for Mastodon compatibility.
• Added guidance on supporting consent-based quote posts per FEP-044f, including how to advertise automatic or manual quote approval, and interoperability notes for Mastodon, Hackers' Pub, and Hollo.

Microformats:

• Introduced a section on using Microformats 2 conventions in HTML content for mentions and hashtags, with practical examples and interoperability recommendations for Mastodon.

• OpenCode:gpt-5.6-terra helped with the overall documentation. I handled the basic content and some of the edits.

[netlify]

✅ Deploy Preview for fedify-json-schema canceled.

Name	Link
🔨 Latest commit	22b03d3
🔍 Latest deploy log	https://app.netlify.com/projects/fedify-json-schema/deploys/6a63256900bbd00008c41aa9

[gemini-code-assist]

Code Review

This pull request updates the pragmatics documentation in docs/manual/pragmatics.md by adding new sections on addressing (to and cc), handling replies, allowing quotes (including FEP-044f and legacy Misskey quotes), and using Microformats 2 for embedding metadata in HTML. Since there are no review comments, I have no feedback to provide.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[coderabbitai]

📝 Walkthrough

Walkthrough

The ActivityPub pragmatics manual now documents audience addressing, reply structure, quote consent policies, and Mastodon-compatible microformats with examples and interoperability guidance.

Changes

ActivityPub pragmatics documentation

Layer / File(s)	Summary
Audience addressing guidance docs/manual/pragmatics.md	Documents primary and secondary to/cc audiences and shows public Note addressing with PUBLIC_COLLECTION and followers.
Replies, quotes, and microformats docs/manual/pragmatics.md	Explains replies through replyTarget/inReplyTo, mention alignment, FEP-044f quote approval, and Mastodon microformat conventions.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• fedify-dev/fedify#709: Updates the same pragmatics manual with related ActivityPub addressing, reply, and microformat guidance.

Suggested labels: type/documentation

Suggested reviewers: sij411

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Out of Scope Changes check	⚠️ Warning	The Microformats section adds unrelated documentation beyond #946’s Note-focused scope.	If intentional, split the Microformats material into a separate PR or add a linked issue covering that scope.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The PR covers the requested to/cc, reply, and quote authorization guidance for #946.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Title check	✅ Passed	The title accurately summarizes the docs-focused changes and mentions the addition of new sections and examples.
Description check	✅ Passed	The description is clearly related to the documentation updates and matches the changes in pragmatics.md.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/manual/pragmatics.md`:
- Around line 801-804: Update the documentation paragraph to use consistent
`cc`/`ccs` terminology, and explicitly state that the enclosing `Create`
activity must copy the complete `to` and `cc` audience lists from its `Note`
object.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 8317533f-a61b-4e1e-8fe6-8ec2e337993e

📥 Commits

Reviewing files that changed from the base of the PR and between 2d46cdb and 41cb247.

📒 Files selected for processing (1)

• docs/manual/pragmatics.md

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ All tests successful. No failed tests found.
see 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[dahlia]

Please correct the three factual issues in the inline comments before this is merged. Please also link #946 from the pull request description so the accepted issue is visible from the pull request.

If an AI tool assisted with any part of this work, please name the tool and describe the extent of its assistance in the pull request description. Please read and follow AI_POLICY.md, and add an Assisted-by: AGENT_NAME:MODEL_VERSION trailer to every affected commit message.

[Bananamilk452]

I wrote this by researching as much as I could with the help of AI, but it seems there were a few issues. I'll make sure to do more thorough research before working on it next time. My apologies.

I've added the explanation and "Assisted-by" tag to the PR description and commit message. I also fixed the issues mentioned above, so please take another look.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/manual/pragmatics.md`:
- Around line 878-889: Clarify the mention-markup documentation by explicitly
distinguishing the minimal Mastodon-compatible `mention u-url` form from the
full Microformats 2 structure using `h-card`, `p-name`, and `u-url`, with
`mention` as an additional class. Update the surrounding examples or explanatory
text consistently, preserving the documented full-form behavior in the section
around the HTML example.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 6aba92d8-7681-401a-b8e9-6fcdcd7127c3

📥 Commits

Reviewing files that changed from the base of the PR and between 41cb247 and 22b03d3.

📒 Files selected for processing (1)

• docs/manual/pragmatics.md

[dahlia]

Thanks!