docs(env): define URL input ownership

[yordis]

• make the URL contract explicit for callers discussing malformed request targets in Tesla does not properly encode URLs #798
• keep encoding, validation, and normalization decisions with applications instead of baking adapter-specific semantics into Tesla

[cursor]

PR Summary

Low Risk
Documentation-only change that clarifies caller expectations for env.url; no runtime behavior or data handling is modified.

Overview
Clarifies the Tesla.Env url type contract by adding @typedoc stating that callers must provide a valid, already-encoded URL/request target (including relative targets when used with Tesla.Middleware.BaseUrl).

Explicitly notes that Tesla won’t validate/normalize/percent-encode URL paths and that middleware may rewrite env.url.

^{Reviewed by Cursor Bugbot for commit e1d1449. Bugbot is set up for automated code reviews on this repo. Configure here.}

[Copilot]

Pull request overview

Clarifies the ownership/contract of Tesla.Env.url to set expectations around URL validity/encoding (context: malformed request targets discussed in #798), keeping encoding/normalization decisions in application code rather than Tesla.

Changes:

• Add @typedoc for t:Tesla.Env.url/0 describing it as a request URL or request target.
• Document that callers should provide a valid, already-encoded value and that Tesla won’t validate/normalize malformed input.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.