docs: auth realm isolation PRD (#2033)

* docs: add auth credential namespace isolation PRD

Document the design for fixing credential caching collisions between
customers with identical identity names. Introduces hybrid namespace
approach with three precedence levels: environment variable,
explicit config, and automatic path hash.

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

* docs: add namespace sanitization specification

Address CodeRabbit feedback by specifying the sanitize() function:
- Define allowed character set (alphanumeric, hyphen, underscore)
- Document sanitization rules (replacement, collapsing, trimming)
- Enforce 64 character maximum length
- Include security considerations for path traversal prevention

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

* docs: rename namespace to realm throughout PRD

Replace all instances of "namespace" with "realm" for credential
isolation terminology:
- ATMOS_AUTH_NAMESPACE → ATMOS_AUTH_REALM
- auth.namespace → auth.realm
- Namespace → Realm in all documentation and code examples

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

* docs: add realm definition to PRD

Add formal definition explaining that a realm is a complete, isolated
authentication universe that determines identity existence, authentication
methods, and credential storage/resolution.

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

* docs: add auth realm architecture PRD

Create comprehensive PRD documenting how realms should be used throughout
the atmos auth system:

- Realm as top-level directory (not appended to provider)
- Default realm computed as SHA256 hash of CliConfigPath
- Data flow from hooks through manager to credential storage
- All touchpoints: files, keyring, PostAuthenticateParams
- Schema and interface changes required
- User experience with atmos auth status

Update existing realm isolation PRD to reference new architecture doc
and align directory structure.

Co-Authored-By: Claude Haiku 4.5 <[email protected]>

* docs: update realm PRDs with validation and directory structure changes

- Replace sanitization with validation (error on invalid characters)
- Update directory structure: ~/.config/atmos/{realm}/{cloud}/{provider}/
- All cloud providers now share common base path with realm as top-level
- Add clear error examples for invalid realm values

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* docs: add realm support to Azure PRD and clarify implementation scope

- Update Azure PRD with realm directory structure (~/.config/atmos/{realm}/azure/)
- Add implementation scope notes to realm PRDs (AWS now, Azure when implemented)
- Update file manager examples to include realm parameter
- Add cross-references between Azure and realm PRDs

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* docs: add consecutive separator check to validation pseudocode

Add missing check for consecutive hyphens/underscores (--/__/-_/_-)
as specified in validation rule #4.

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* docs: fix broken XDG specification link in Azure PRD

Co-Authored-By: Claude Opus 4.5 <[email protected]>

* docs: fix error handling and keyring key format in realm PRDs

- Fix NewAuthManager to properly handle error from realm.GetRealm()
- Fix createKeyringKey to use atmos:{realm}:{identity} format without providerName
  (consistent with architecture PRD's keyring storage design)

Co-Authored-By: Claude Opus 4.5 <[email protected]>

---------

Co-authored-by: Claude Haiku 4.5 <[email protected]>

Author: Benbentwo