docs(auth): scope Bitbucket Cloud examples to api.bitbucket.org

Copilot review round 3 on #4629: both ready-to-paste Bitbucket Cloud
examples listed hosts=["api.bitbucket.org", "bitbucket.org"], but
Bitbucket Cloud splits its auth surface by host. Verified against
Atlassian's docs (support.atlassian.com/bitbucket-cloud/docs/
using-access-tokens/) and developer.atlassian.com/cloud/bitbucket/rest/,
plus a live probe (bitbucket.org/.../raw/... varies its response on the
`authorization` header, consistent with HTTP Basic, not Bearer):

- api.bitbucket.org accepts Bearer access tokens and Basic with an
  Atlassian API token on any REST call.
- The plain bitbucket.org web host (raw links, git-over-HTTPS) does not
  accept either — it authenticates via HTTP Basic with the literal
  username x-token-auth and the access token as the password, a
  different credential shape than either documented example produces.

Restrict both examples' `hosts` to `api.bitbucket.org`, and point catalog
fetches at the API's `/2.0/repositories/<ws>/<repo>/src/<ref>/<path>`
form instead of `bitbucket.org/.../raw/...`, so the credential in
auth.json actually authenticates the request it's attached to. No code
changes — the provider already implements both schemes correctly; only
the documented host scope was wrong.

Assisted-by: Claude Code (model: claude-sonnet-5, human-supervised)
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: CrazyBaran

docs/reference/authentication.md

@@ -146,28 +146,42 @@ Requires `az login` to have been run beforehand.
 
 | Scheme | Header | Use for |
 |---|---|---|
-| `bearer` | `Authorization: Bearer <token>` | Repository / project / workspace access tokens (Bitbucket Cloud), HTTP access tokens (Bitbucket Data Center) |
-| `basic` | `Authorization: Basic base64(<username>:<token>)` | Atlassian API tokens (username = Atlassian account email). Bitbucket Cloud app passwords were removed by Atlassian on July 28, 2026 — use an API token or an access token instead. |
+| `bearer` | `Authorization: Bearer <token>` | Repository / project / workspace access tokens and Atlassian API tokens (Bitbucket Cloud, **`api.bitbucket.org` only** — see note below), HTTP access tokens (Bitbucket Data Center) |
+| `basic` | `Authorization: Basic base64(<username>:<token>)` | Atlassian API tokens (username = Atlassian account email) against `api.bitbucket.org`. Bitbucket Cloud app passwords were removed by Atlassian on July 28, 2026 — use an API token or an access token instead. |
+
+> **Host note:** Bitbucket Cloud splits its surface by host. `api.bitbucket.org`
+> accepts a Bearer access token or Basic-with-Atlassian-API-token on any
+> REST call, including fetching a catalog file via
+> `GET /2.0/repositories/<workspace>/<repo>/src/<ref>/<path>`. The plain
+> `bitbucket.org` web host (browser pages, `.../raw/...` links, `git clone`
+> over HTTPS) does **not** accept either of those — it authenticates
+> git-over-HTTPS with HTTP Basic using the literal username `x-token-auth`
+> and the access token as the password. Point catalog and `download_url`
+> entries at `api.bitbucket.org` (below) rather than `bitbucket.org/.../raw/...`
+> so the credentials in your `auth.json` actually apply.
 
 **Example — Bitbucket Cloud access token (recommended):**
 
 ```json
 {
-  "hosts": ["api.bitbucket.org", "bitbucket.org"],
+  "hosts": ["api.bitbucket.org"],
   "provider": "bitbucket",
   "auth": "bearer",
   "token_env": "BITBUCKET_ACCESS_TOKEN"
 }
 ```
 
 Create the token with the **Repositories: Read** scope on the repository
-(or project/workspace) that hosts your catalogs and archives.
+(or project/workspace) that hosts your catalogs and archives. Fetch a
+catalog file with this credential via
+`https://api.bitbucket.org/2.0/repositories/<workspace>/<repo>/src/<ref>/catalog.json`
+rather than a `bitbucket.org/.../raw/...` URL.
 
 **Example — Atlassian API token (Basic auth):**
 
 ```json
 {
-  "hosts": ["api.bitbucket.org", "bitbucket.org"],
+  "hosts": ["api.bitbucket.org"],
   "provider": "bitbucket",
   "auth": "basic",
   "username": "you@example.com",