docs: update modelling example

[omer-topal]

Summary by CodeRabbit

Release Notes

• Documentation
  • Clarified and operator behavior in permission modeling documentation with improved explanations of how it intersects user sets across organizations
  • Enhanced examples demonstrating intersection scenarios for better understanding of permission definitions

[coderabbitai]

📝 Walkthrough

Walkthrough

Documentation update clarifying how the Permify and operator works: it intersects resolved user sets of its operands. Examples now explicitly show independent evaluation across organizations followed by intersection, with guidance on constraining intersection scope through permission definition placement.

Changes

Cohort / File(s)	Summary
Documentation: and Operator Semantics docs/getting-started/modeling.mdx	Clarified and operator behavior as set intersection of independently resolved operands. Added examples distinguishing intersection across all reachable organizations versus intersection constrained to single organization. Fixed trailing whitespace in permission delete definition.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• docs: update modeling section for DSL expression confusion #1677: Modifies the same documentation file to clarify and operator semantics and examples in the modeling DSL.
• docs(getting-started): review of authorization model for typos and clarity #2708: Updates modeling documentation with clarifications on operator semantics (including intersection behavior for and/or/not operators).
• docs: make cross entities beta feature #1801: Updates modeling documentation with focus on how permission intersections and the and operator work in practice.

Suggested reviewers

• ucatbas

Poem

🐰 Hop along, dear readers, through logic refined,
Where and now clearly shows intersection designed,
Sets resolved and combined in scopes bright,
Our docs now spell out what's wrong and what's right! ✨

🚥 Pre-merge checks | ✅ 3

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: update modelling example' accurately summarizes the main change—updating documentation with clarified modeling examples for the Permify and operator.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch omer/update-modeling-example

---

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 and usage tips.}

[coderabbitai]

🧹 Nitpick comments (1)

docs/getting-started/modeling.mdx (1)

275-297: Consider adding one concrete tuple-level example for the cross-org vs same-org distinction.

The explanation is good; a 2–3 tuple mini-example here would make the “member in org A + admin in org B” vs “both on same org” contrast instantly obvious to readers.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@docs/getting-started/modeling.mdx` around lines 275 - 297, Add a short 2–3
tuple example demonstrating the cross-org vs same-org difference using the
existing entities/relations (entity user, organization with relations member and
admin, repository with relation org and permission delete). Show one set of
tuples where user is member of organization A and admin of organization B and
indicate repository.delete is NOT granted, and a second set where the user is
both member and admin on the same organization and indicate repository.delete IS
granted; reference the permission names (organization.delete and
repository.delete) and the relations (organization.member, organization.admin,
repository.org) so readers can immediately see the different outcomes.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In `@docs/getting-started/modeling.mdx`:
- Around line 275-297: Add a short 2–3 tuple example demonstrating the cross-org
vs same-org difference using the existing entities/relations (entity user,
organization with relations member and admin, repository with relation org and
permission delete). Show one set of tuples where user is member of organization
A and admin of organization B and indicate repository.delete is NOT granted, and
a second set where the user is both member and admin on the same organization
and indicate repository.delete IS granted; reference the permission names
(organization.delete and repository.delete) and the relations
(organization.member, organization.admin, repository.org) so readers can
immediately see the different outcomes.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 14fc25af-1231-485c-918c-4a5c65b53f5e

📥 Commits

Reviewing files that changed from the base of the PR and between a9eadfa and e45da4c.

📒 Files selected for processing (1)

• docs/getting-started/modeling.mdx

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.59%. Comparing base (8f76cf4) to head (e45da4c).
⚠️ Report is 10 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2837      +/-   ##
==========================================
+ Coverage   82.58%   82.59%   +0.02%     
==========================================
  Files          74       74              
  Lines        8297     8297              
==========================================
+ Hits         6851     6852       +1     
+ Misses        910      909       -1     
  Partials      536      536              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.