docs: document route ownership conventions for FastAPI AI extensions (fixes #120)

[Kakarot679]

Summary

Adds docs/recipes/FASTAPI_AI_ROUTE_OWNERSHIP.md for #120, so contributors can see which route prefixes are taken before adding a FastAPI AI extension. Covers how routers reach the generated app, the prefixes in use, the provider hook for middleware, and the env namespaces.

/rag is documented as unclaimed on purpose: fastapi-rag-pgvector ships a service layer with no router, so it composes with fastapi-ai-chat instead of competing for the prefix.

Also corrects the incompatibleWith row in AI_ML_AUTHORING.md, which still said fastapi-ai-chat did not exist yet, and links both docs from the README table.

Closes#120

Testing

Docs only, no generated-project behavior changes.

• python scripts/ci/validate-registry.py passes
• python scripts/ci/generate-matrix.py --layer validate-profiles passes
• Checked each prefix, provider hook and env namespace against the extension sources.

Checklist

• I kept this pull request focused on one concern.
• I added or updated tests when behavior changed.
• I updated documentation when user-facing behavior changed.
• I verified formatting and relevant checks locally.

[coderabbitai]

Warning

Review limit reached

@Kakarot679, you've reached your PR review limit, so we couldn't start this review.

Next review available in:46 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2666206a-e4ee-4bc8-9332-d2ee26b7fea7

📥 Commits

Reviewing files that changed from the base of the PR and between 5c7171c and 6042d5e.

📒 Files selected for processing (2)

• docs/AI_ML_AUTHORING.md
• docs/recipes/FASTAPI_AI_ROUTE_OWNERSHIP.md

📝 Walkthrough

Walkthrough

The PR adds FastAPI AI route ownership guidance, updates extension conflict documentation, and links the new guide from the README and AI/ML authoring documentation.

Changes

FastAPI AI route ownership

Layer / File(s)	Summary
Route ownership guide docs/recipes/FASTAPI_AI_ROUTE_OWNERSHIP.md	Documents route mounting, reserved prefixes, /rag behavior, router conventions, middleware hooks, environment namespaces, collision declarations, and implementation checks.
Documentation integration docs/AI_ML_AUTHORING.md, README.md	Updates extension ownership guidance and adds links to the route ownership documentation.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• Create-Python-App/cpa-templates#166: Extends the same FastAPI AI route-ownership documentation and incompatibleWith guidance.

Suggested reviewers:ulises-jeremias

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes satisfy issue #120 by documenting /chat and /rag ownership, middleware hooks, and route-prefix conventions.
Out of Scope Changes check	✅ Passed	The README links and compatibility correction directly support the documented route-ownership conventions; no unrelated changes are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the documentation changes for route ownership conventions in FastAPI AI extensions.

✨ 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: 2

🤖 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/recipes/FASTAPI_AI_ROUTE_OWNERSHIP.md`:
- Around line 9-16: Update the route-order statement in the documented routing
guidance to clarify that shadowing occurs only when an earlier route has both
the same path and the same HTTP method; routes sharing a path but serving
different methods may still be matched separately.
- Line 36: Update the route-order warning in the ownership guidance to apply
only when another router claims the same path and HTTP method; clarify that
differing methods may still be handled by a later route. Preserve the existing
guidance about avoiding occupied `/rag` paths and the `/chat` ownership
boundary.

🪄 Autofix

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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 2e09ccc4-4351-40c4-a8c4-69a36c5ad6c3

📥 Commits

Reviewing files that changed from the base of the PR and between 62aacc3 and 5c7171c.

📒 Files selected for processing (3)

• README.md
• docs/AI_ML_AUTHORING.md
• docs/recipes/FASTAPI_AI_ROUTE_OWNERSHIP.md