docs: add operational guides and technical FAQs

[omer-topal]

Summary by CodeRabbit

• Documentation
  • New Watch API operational guidance covering performance considerations, scaling strategies, and reconnection best practices
  • Enhanced cache documentation detailing sizing, eviction behavior, and scaling event dynamics
  • Expanded FAQ section with guidance on attribute type migrations and schema management
  • Added profiler configuration documentation with practical examples and best practices
  • Improved relation field explanations with explicit examples and use cases
  • New Kubernetes operational notes addressing cache warm-up and stream reconnection after scaling events

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR adds comprehensive operational guidance documentation for the Watch API and enhances existing documentation with scaling strategies, cache sizing information, and configuration details. It expands content across operations, configuration, and deployment sections while improving clarity in existing guides.

Changes

Cohort / File(s)	Summary
Watch API Documentation docs/operations/watch.mdx, docs/api-reference/watch/watch-changes.mdx	New operational guidance page for Watch API at scale covering performance, mitigation strategies, tuning parameters, and reconnection best practices. Cross-reference added to existing watch-changes documentation.
Operations & Cache Guidance docs/operations/cache.mdx	Added Cache Sizing & Eviction section describing snap token integration, introduced Scaling Events subsections for Data and Distributed Caches, and expanded Consistent Hashing explanation with scale-out/in dynamics and cache behavior during pod events.
Configuration & Deployment docs/setting-up/configuration.mdx, docs/setting-up/installation/kubernetes.mdx	Enhanced configuration documentation with detailed Go pprof profiler section including endpoints and usage examples. Added operational notes for Kubernetes scaling including cache warm-up and Watch API stream reconnection guidance.
Content Improvements docs/getting-started/sync-data.mdx, docs/permify-overview/faqs.mdx	Clarified subject relation field explanations with structured bullet points and examples. Added FAQ section on attribute type migrations with required steps and schema versioning details.
Navigation docs/mint.json	Added operations/watch to the Operations navigation group, linking to new operational guidance documentation.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested reviewers

• ucatbas

Poem

🐰 The docs now gleam with Watch's great might,
Cache scaling tales and profiles bright,
From Kubernetes pods to reconnect streams,
Operational wisdom fulfills our dreams,
Operations guide us through scale's delight! ✨

🚥 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 accurately summarizes the main changes across the pull request, which add new documentation pages and sections for operational guidance and FAQs.
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
• Post copyable unit tests in a comment
• Commit unit tests in branch omer/add-technical-faqs

Tip

Try Coding Plans. Let us write the prompt for your AI agent so you can ship faster (with fewer bugs).
Share your feedback on Discord.

---

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.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 82.63%. Comparing base (5556f54) to head (2cc5331).
⚠️ Report is 2 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #2816      +/-   ##
==========================================
- Coverage   82.64%   82.63%   -0.01%     
==========================================
  Files          74       74              
  Lines        8126     8126              
==========================================
- Hits         6715     6714       -1     
- Misses        892      893       +1     
  Partials      519      519              

☔ 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.