docs: document cross-repository blob mount and re-auth loop

What does this MR do?

Adds a dedicated doc, docs/cross-repository-blob-mount.md, covering how the cross-repository blob mount works end to end:

• How the client discovers a mount source (the client-side v2MetadataService mount-candidate cache), and why a fresh machine or a stale cache changes the outcome.
• The three outcomes of a mount attempt — 201 Created (mounted), 202 Accepted (authorized but nothing to mount → falls through to a normal upload), and 401 Unauthorized (token lacks <source>:pull) — and the distinction between them.
• The mid-push re-authorization loop: a mount needs pull on the source repo, which is a different scope from the push,pull obtained for the target, so a mount can force a fresh trip to the auth server to widen the token before retrying.

The existing flow diagrams (push-pull-request-flow.md, auth-request-flow.md) show the mount branch but omit the auth dimension and the 401-vs-202 distinction, which is enforced in auth middleware before StartBlobUpload runs. The new doc is cross-linked from both.

Grounded against the code: registry/handlers/app.go (the from= access record), registry/handlers/blobupload.go (the 201-vs-202 mount handler), and registry/auth/token/accesscontroller.go (token verification and the insufficient_scope challenge).

Docs only — no code or behavior changes.

Related to

Author checklist

• CODEOWNERS Review: This MR requires approval from at least one CODEOWNER per category/file.
  • If codeowners are absent or the change is urgent, any registry maintainer can temporarily disable CODEOWNERS reviews in the project settings. When doing so:
    • Add a comment on the MR justifying the bypass
    • Mention/CC the designated codeowners in the MR for async review
    • Re-enable CODEOWNERS reviews in project settings once the MR is merged
  • If you lack permissions to disable CODEOWNERS reviews, reach out to the Engineering Manager (@jaime) or Senior Engineering Manager (@crystalpoole) for assistance.
• Assign one of conventional-commit prefixes to the MR.
  • fix: Indicates a bug fix, triggers a patch release.
  • feat: Signals the introduction of a new feature, triggers a minor release.
  • perf: Focuses on performance improvements that don't introduce new features or fix bugs, triggers a patch release.
  • docs: Updates or changes to documentation. Does not trigger a release.
  • style: Changes that do not affect the code's functionality. Does not trigger a release.
  • refactor: Modifications to the code that do not fix bugs or add features but improve code structure or readability. Does not trigger a release.
  • test: Changes related to adding or modifying tests. Does not trigger a release.
  • chore: Routine tasks that don't affect the application, such as updating build processes, package manager configs, etc. Does not trigger a release.
  • build: Changes that affect the build system or external dependencies. May trigger a release.
  • ci: Modifications to continuous integration configuration files and scripts. Does not trigger a release.
  • revert: Reverts a previous commit. It could result in a patch, minor, or major release.
• MR contains database changes including schema/background migrations:
  • Do not include code that depends on the schema migrations in the same commit. Split the MR into two or more.
  • Do not include code that depends on background migrations in the same release.
  • Manually run up and down migrations in a postgres.ai production database clone and add a link for the query plan(s) to the MR.
  • If adding new schema migrations make sure the REGISTRY_SELF_MANAGED_RELEASE_VERSION CI variable in migrate.yml is pointing to the latest GitLab self-managed released registry version. Find the correct registry version here. Make sure to select the branch of the latest GitLab release.
  • If adding new queries, extract a query plan from postgres.ai and post the link here. If changing existing queries, also extract a query plan for the current version for comparison.
    • I do not have access to postgres.ai and have made a comment on this MR asking for these to be run on my behalf.
  • If adding new background migration, follow the guide for performance testing new background migrations and add a report/summary to the MR with your analysis.
• Change contains a breaking change - apply the breaking change label.
• Change is considered high risk - apply the label high-risk-change
• I created or linked to an existing issue for every added or updated TODO, BUG, FIXME or OPTIMIZE prefixed comment
• Changes cannot be rolled back
  • Apply the label cannot-rollback.
  • Add a section to the MR description that includes the following details:
    • The reasoning behind why a release containing the presented MR can not be rolled back (e.g. schema migrations or changes to the FS structure)
    • Detailed steps to revert/disable a feature introduced by the same change where a migration cannot be rolled back. (note: ideally MRs containing schema migrations should not contain feature changes.)
    • Ensure this MR does not add code that depends on these changes that cannot be rolled back.

Documentation/resources

Code review guidelines

Go Style guidelines

Feature flags

When documentation is required

Documentation workflow

Reviewer checklist

• Ensure the commit and MR tittle are still accurate.
• If the change contains a breaking change, verify the breaking change label.
• If the change is considered high risk, verify the label high-risk-change
• Identify if the change can be rolled back safely. (note: all other reasons for not being able to rollback will be sufficiently captured by major version changes).