docs: canonical multi-profile --ref page for Identity-layer consumers (anchors google-readonly#179, google-readwrite#2)

[zzwong]

Goal

Canonical home for the multi-profile usage documentation requested in open-cli-collective/google-readonly#179 and open-cli-collective/google-readwrite#2. The mechanism those issues document — the global --ref <service>/<profile> selector, <SERVICE>_CREDENTIAL_REF, and the --ref flag > env > config credential_ref precedence — lives in this library's Identity layer, so per google-readonly#152's no-duplication rule the shared prose belongs here, with each consumer CLI carrying only a thin link plus its own framing (read-side census recipes for gro, destructive-op identity assertion for grw).

Scope

• A docs/ page (e.g. docs/multi-profile.md) covering, once, for all Identity-layer consumers:
  • Pin every invocation with --ref/env on multi-account machines; never rewrite the global credential_ref as a switching mechanism (shared mutable state; concurrent invocations race — the failure mode that motivated the selector in google-readonly#166).
  • Identity assertion as the first call of a session: <cli> --ref <service>/<profile> me, asserting the expected account before the first real operation.
  • The full precedence chain, stated in one place.
  • Known caveat: token refresh currently resolves the OAuth client from the single global oauth_client_path, so profiles minted from different OAuth clients break on refresh — google-readonly#178 (the fix for which also lands in this repo, in auth/auth.go / initcmd/init.go).
• Consumer repos then close google-readonly#179 and google-readwrite#2 by linking this page from their agent-guidance indexes.

Acceptance Criteria

• One shared page here; zero duplicated multi-profile prose in consumer repos.
• The anti-pattern (global-ref rewriting) and the replacement (pinning + identity assertion) are both named explicitly.
• google-readonly#178 is referenced as a caveat until its fix ships.