docs(auth): add Plugin Authorization page for the routes-derived surface

[maxdubrinsky]

What

A human-facing Plugin Authorization page documenting the routes-derived plugin authz surface (#332), for plugin authors.

Changes

• New docs/auth/authorization/plugin-authorization.mdx: how plugin authz is derived from routes, the service.resource.action permission grammar, OAuth scopes, caller kinds, the job/function route factories (authz=), extra_permissions / extra_role_permissions, the on_invalid_plugin fail modes, and how to verify a plugin's authz.
• Nav: added to the Authorization section in versions/latest.yml (between Permissions Reference and Policy Engine).
• Cross-link: the "Writing Plugins" section of plugins.mdx now covers authz and links the new page, with an authz note on the HTTP-service surface row.

Verification

• Nav YAML parses; the new page path resolves; mdx frontmatter valid; all internal doc links resolve to real pages.
• fern check could not run locally (broken local fern install, EPERM reading its own CLI); docs CI runs the real fern validation on this PR.

Summary by CodeRabbit

• Documentation
  • Added clearer guidance for plugin HTTP route authorization, including required per-route rules, supported caller types, and how authorization is validated.
  • Expanded the plugin authorization reference with details on permission formats, OAuth scope behavior, extra permissions, and verification steps.
  • Added the new Plugin Authorization page to the authorization documentation navigation.

[github-actions]

🌿 Preview your docs: https://nvidia-preview-plugin-authz-docs-md.docs.buildwithfern.com/nemo-platform

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 97562b7b-9112-4150-ad94-bba17dfebe40

📥 Commits

Reviewing files that changed from the base of the PR and between 47d6eea and 3752902.

📒 Files selected for processing (3)

• docs/agents/plugins.mdx
• docs/auth/authorization/plugin-authorization.mdx
• docs/fern/versions/latest.yml

---

📝 Walkthrough

Walkthrough

This PR adds documentation for plugin HTTP route authorization, describing route-derived permission catalogs, caller kinds, OAuth scopes, route factory requirements, extra permissions, and fail-closed validation behavior. It updates the plugin authoring guide and adds a navigation entry for the new page.

Changes

Plugin Authorization Documentation

Layer / File(s)	Summary
Plugin authoring guide updates docs/agents/plugins.mdx	Notes that every HTTP route must declare authorization and adds guidance on @path_rule, authz= in route factories, and fail-closed behavior.
Plugin authorization overview and model docs/auth/authorization/plugin-authorization.mdx	Introduces the new page explaining route-derived authorization, permission id grammar, PermissionSet/perm, AuthzScope, and caller kinds.
Declaring authorization on routes and factories docs/auth/authorization/plugin-authorization.mdx	Documents hand-written route decoration, job/function route factory authz= requirements, and extra_permissions/extra_role_permissions.
Validation, verification, and navigation docs/auth/authorization/plugin-authorization.mdx, docs/fern/versions/latest.yml	Covers NMP_AUTH_ON_INVALID_PLUGIN fail modes, verification commands, related links, and adds the page to the doc navigation.

Possibly related PRs

• NVIDIA-NeMo/nemo-platform#332: Documents the same @path_rule-driven, fail-closed per-route authorization model implemented there.
• NVIDIA-NeMo/nemo-platform#368: Also modifies docs/fern/versions/latest.yml navigation for the Access Control section.

Suggested labels: docs

Suggested reviewers: anastasia-nesterenko, svvarom, mckornfield

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly describes the main change: adding a Plugin Authorization page for route-derived plugin authz.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch plugin-authz-docs/md

---

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

[github-actions]

Suite	Lines Covered	Line Rate	Branch Rate
Unit Tests	22510/29625	76.0%	60.9%
Integration Tests	13002/28305	45.9%	19.4%

[ironcommit]

LGTM