[PM-26337] Create a Claude markdown file (#16676)

* Initial claude markdown with lots of help from the team.

.github/workflows/lint.yml

@@ -49,6 +49,7 @@ jobs:
             ! -path "*/Cargo.toml" \
             ! -path "*/Cargo.lock" \
             ! -path "./apps/desktop/macos/*" \
+            ! -path "*/CLAUDE.md" \
             > tmp.txt
           diff <(sort .github/whitelist-capital-letters.txt) <(sort tmp.txt)
 

CLAUDE.md

@@ -0,0 +1,90 @@
+# Bitwarden Clients - Claude Code Configuration
+
+## Critical Rules
+
+- **NEVER** use code regions: If complexity suggests regions, refactor for better readability
+
+- **CRITICAL**: new encryption logic should not be added to this repo.
+
+- **NEVER** send unencrypted vault data to API services
+
+- **NEVER** commit secrets, credentials, or sensitive information. Follow the guidelines in `SECURITY.md`.
+
+- **NEVER** log decrypted data, encryption keys, or PII
+  - No vault data in error messages or console logs
+
+- **ALWAYS** Respect configuration files at the root and within each app/library (e.g., `eslint.config.mjs`, `jest.config.js`, `tsconfig.json`).
+
+## Mono-Repo Architecture
+
+This repository is organized as a **monorepo** containing multiple applications and libraries. The
+main directories are:
+
+- `apps/` – Contains all application projects (e.g., browser, cli, desktop, web). Each app is
+  self-contained with its own configuration, source code, and tests.
+- `libs/` – Contains shared libraries and modules used across multiple apps. Libraries are organized
+  by team name, domain, functionality (e.g., common, ui, platform, key-management).
+
+**Strict boundaries** must be maintained between apps and libraries. Do not introduce
+cross-dependencies that violate the intended modular structure. Always consult and respect the
+dependency rules defined in `eslint.config.mjs`, `nx.json`, and other configuration files.
+
+## Angular Architecture Patterns
+
+**Observable Data Services (ADR-0003):**
+
+- Services expose RxJS Observable streams for state management
+- Components subscribe using `async` pipe (NOT explicit subscriptions in most cases)
+  Pattern:
+
+```typescript
+// Service
+private _folders = new BehaviorSubject<Folder[]>([]);
+readonly folders$ = this._folders.asObservable();
+
+// Component
+folders$ = this.folderService.folders$;
+// Template: <div *ngFor="let folder of folders$ | async">
+```
+
+For explicit subscriptions, MUST use `takeUntilDestroyed()`:
+
+```typescript
+constructor() {
+  this.observable$.pipe(takeUntilDestroyed()).subscribe(...);
+}
+```
+
+**Angular Signals (ADR-0027):**
+
+Encourage the use of Signals **only** in Angular components and presentational services.
+
+Use **RxJS** for:
+
+- Services used across Angular and non-Angular clients
+- Complex reactive workflows
+- Interop with existing Observable-based code
+
+**NO TypeScript Enums (ADR-0025):**
+
+- Use const objects with type aliases instead
+- Legacy enums exist but don't add new ones
+
+Pattern:
+
+```typescript
+// ✅ DO
+export const CipherType = Object.freeze({
+  Login: 1,
+  SecureNote: 2,
+} as const);
+export type CipherType = (typeof CipherType)[keyof typeof CipherType];
+
+// ❌ DON'T
+enum CipherType {
+  Login = 1,
+  SecureNote = 2,
+}
+```
+
+Example: `/libs/common/src/vault/enums/cipher-type.ts`

apps/browser/CLAUDE.md

@@ -0,0 +1,22 @@
+# Browser Extension - Critical Rules
+
+- **NEVER** use `chrome.*` or `browser.*` APIs directly in business logic
+  - Always use `BrowserApi` abstraction: `/apps/browser/src/platform/browser/browser-api.ts`
+  - Required for cross-browser compatibility (Chrome/Firefox/Safari/Opera)
+
+- **ALWAYS** use `BrowserApi.addListener()` for event listeners in popup context
+  - Safari requires manual cleanup to prevent memory leaks
+  - DON'T use native `chrome.*.addListener()` or `browser.*.addListener()` directly
+
+- **CRITICAL**: Safari has tab query bugs
+  - Use `BrowserApi.tabsQueryFirstCurrentWindowForSafari()` when querying current window tabs
+  - Safari can return tabs from multiple windows incorrectly
+
+## Manifest V3
+
+- Extension uses Web Extension API Manifest V3
+- **Service workers replace background pages**
+  - Background context runs as service worker (can be terminated anytime)
+  - DON'T assume background page persists indefinitely
+  - Use message passing for communication between contexts
+  - `chrome.extension.getBackgroundPage()` returns `null` in MV3

apps/cli/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLI - Critical Rules
+
+- **ALWAYS** output structured JSON when `process.env.BW_RESPONSE === "true"`
+  - Use Response objects (MessageResponse, ListResponse, etc.) from `/apps/cli/src/models/response/`
+  - DON'T write free-form text that breaks JSON parsing
+
+- **NEVER** use `console.log()` for output
+  - Use `CliUtils.writeLn()` to respect `BW_QUIET` and `BW_RESPONSE` environment variables
+  - Use the `ConsoleLogService` from the `ServiceContainer`
+
+- **ALWAYS** respect `BW_CLEANEXIT` environment variable
+  - Exit code 0 even on errors when `BW_CLEANEXIT` is set
+  - Required for scripting environments that need clean exits

apps/desktop/CLAUDE.md

@@ -0,0 +1,11 @@
+# Desktop (Electron) - Critical Rules
+
+- **CRITICAL**: Separate main process vs renderer process contexts
+  - Main process: Node.js + Electron APIs (files in `/apps/desktop/src/main/`)
+  - Renderer process: Browser-like environment (Angular app files)
+  - Use IPC (Inter-Process Communication) for cross-process communication
+
+- **NEVER** import Node.js modules directly in renderer process
+- **NEVER** import Angular modules in the main process
+  - Use preload scripts or IPC to access Node.js functionality
+  - See `/apps/desktop/src/*/preload.ts` files for patterns

apps/web/CLAUDE.md

@@ -0,0 +1,13 @@
+# Web Vault - Critical Rules
+
+- **NEVER** access browser extension APIs
+  - Web vault runs in standard browser context (no chrome._/browser._ APIs)
+  - DON'T import or use BrowserApi or extension-specific code
+
+- **ALWAYS** assume multi-tenant organization features
+  - Web vault supports enterprise organizations with complex permissions
+  - Use organization permission guards: `/apps/web/src/app/admin-console/organizations/guards/`
+
+- **CRITICAL**: All sensitive operations must work without local storage
+  - Web vault may run in environments that clear storage aggressively
+  - DON'T rely on localStorage/sessionStorage for security-critical data