docs: multi-profile --ref discipline for a write-capable CLI (companion to google-readonly#179)

[zzwong]

Goal

Companion to open-cli-collective/google-readonly#179: give grw the same agent-facing multi-profile documentation, with the write-side framing that makes it matter more here. grw ships the identical global --ref selector from the shared Identity layer, but the repo currently has no docs/ directory and nothing that teaches the pinning discipline — and on a write-capable CLI, a misbound invocation doesn't read the wrong mailbox, it deletes mail or rewrites filters in the wrong account.

Scope

• Profile pinning as a precondition for destructive operations. Same rules as gro#179 (pin every invocation with --ref <service>/<profile> or <SERVICE>_CREDENTIAL_REF; never rewrite the global credential_ref to switch accounts), plus the grw-specific recipe: assert identity with grw --ref <service>/<profile> me before the first delete, filters, or label mutation of a session, not just before reads.
• Search flag surface is shared with gro (--max/-m not -n, --ids piping into bulk write commands) — cover by reference to wherever gro#179's material lands rather than duplicating.
• Canonical home: per google-readonly#152's no-duplication rule, the shared profile-discipline prose likely belongs in google-cli-common/docs with both CLIs linking to it; this issue is satisfied by a thin grw doc (or AGENTS.md index entry) that adds the write-stakes framing and links the canonical page.

Related

• google-readonly#178 (per-profile OAuth client refresh breakage) lives in the shared layer and affects grw identically — worth a caveat line in whatever doc lands, until fixed.

Acceptance Criteria

• grw has a linked doc or index entry covering profile pinning with the identity-assertion-before-destructive-ops recipe.
• The anti-pattern (rewriting global credential_ref to switch accounts) is named explicitly.
• Shared material is linked, not duplicated, per google-readonly#152.