docs: rewrite the custom resources guide for the reconcile flow

[rohilsurana]

What

Rewrites the "Custom Resources and Permissions" guide to match the new model. The boot-time resources_config_path loader is gone (removed in #1767), so custom permissions and roles are registered through the frontier reconcile flow or the admin API now, not a config file read at startup.

Changes:

• Rewrites "How custom resources are registered": the reconcile Permission / Role document format, the frontier reconcile and frontier export commands, and the reconcile rules (identity-only permissions, delete needs delete: true, app/... namespaces rejected).
• Explains what happens when a permission is registered: AppendSchema regenerates the schema (base schema plus every permission in the database) and writes to Postgres and SpiceDB, and the same step runs at boot.
• Keeps the accurate schema-generation and role-mapping sections, updated for the new flow.
• Updates the user/project proxy section: app/... namespaces are now rejected with an error by both reconcile and the admin API, instead of being silently ignored from a config file.
• Updates the role examples to kind: Role documents and the reconcile role semantics: a listed field is the whole desired value (so listing permissions replaces the set), while an omitted field keeps the role's default.
• Removes emdashes to match our writing style.

Why

The old guide described the removed boot-time config-file loader end to end. #1767 added a short banner as a stopgap; this replaces the banner with a full rewrite.

Stacked on #1767

This is stacked on chore/remove-resources-config-path-flow (#1767), because the guide describes the world after that PR removes the loader. Retarget to main once #1767 merges.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
frontier	Ready	Preview	Aug 11, 2026 4:56pm

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: a8b2f78c-cda4-4791-92fb-37e4ff2c8608

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

📝 Walkthrough

Summary by CodeRabbit

• Documentation
  • Updated custom-resource registration guidance to use frontier reconcile and the admin API.
  • Added instructions for declarative permission reconciliation, export, validation, and deletion.
  • Documented schema persistence and automatic reapplication after startup.
  • Expanded examples for permissions, roles, project-level capabilities, role replacement, and custom-role deletion.

Walkthrough

The custom-resource authorization guide now documents declarative registration through frontier reconcile and the admin API. It covers permission validation, schema persistence, project-level permissions, role permission semantics, and custom-role deletion.

Changes

Custom-resource authorization documentation

Layer / File(s)	Summary
Registration and permission workflow docs/content/docs/authz/custom-resources.mdx	Documents reconcile and admin API registration, permission validation, export, schema persistence, startup reapplication, and project-level permission examples.
Permission model reference docs/content/docs/authz/custom-resources.mdx	Updates rule descriptions, permission-check examples, punctuation, and default access guidance.
Role reconciliation and lifecycle docs/content/docs/authz/custom-resources.mdx	Replaces configuration-based role examples with reconcile resources and documents permission replacement, default preservation, and deletion markers.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• raystack/frontier#1713: Both PRs update the custom-resource authorization documentation.
• raystack/frontier#1751: This PR documents the declarative reconciliation workflow and custom Permission and Role behavior.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

---

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

[coveralls]

Coverage Report for CI Build 31482211217

Coverage remained the same at 48.082%

Details

• Coverage remained the same as the base build.
• Patch coverage: No coverable lines changed in this PR.
• No coverage regressions found.

Uncovered Changes

No uncovered changes found.

Coverage Regressions

No coverage regressions found.

---

Coverage Stats

Relevant Lines:	39861
Covered Lines:	19166
Line Coverage:	48.08%
Coverage Strength:	15.39 hits per line

---

💛 - Coveralls

[rohilsurana]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0213da99-fd48-4378-92cc-253bcb9a9ad1

📥 Commits

Reviewing files that changed from the base of the PR and between b74cbdb and f4464dc.

📒 Files selected for processing (1)

• docs/content/docs/authz/custom-resources.mdx

[rohilsurana]

Automated code review (xhigh) of the docs rewrite. Findings below, most important first. The first two are worth fixing before merge: the main example and the "omitting permissions" note both describe reconcile as adding/keeping permissions when it actually replaces the whole set, so a reader following them would strip permissions from built-in roles.