Refactor CLAUDE.md documentation to improve AI code review guidance (#586)

Author: theMickster

.claude/CLAUDE.md

@@ -1,61 +1,125 @@
 # Bitwarden Internal SDK
 
-Rust SDK centralizing business logic. You're reviewing code as a senior Rust engineer mentoring
-teammates.
+Cross-platform Rust SDK implementing Bitwarden's core business logic.
 
-## Client Pattern
+**Rust Edition:** The SDK targets the
+[2024](https://doc.rust-lang.org/nightly/edition-guide/rust-2024/index.html) edition of Rust.
 
-PasswordManagerClient ([bitwarden-pm](crates/bitwarden-pm/src/lib.rs)) wraps
-[bitwarden_core::Client](crates/bitwarden-core/src/client/client.rs) and exposes sub-clients:
-`auth()`, `vault()`, `crypto()`, `sends()`, `generators()`, `exporters()`.
+**Crate documentation**: Before working in any crate, read available documentation: `CLAUDE.md` for
+critical rules, `README.md` for architecture, `examples/` for usage patterns, and `tests/` for
+integration tests. **Before making changes or reviewing code, review relevant examples and tests for
+the specific functionality you're modifying.**
 
-**Lifecycle**
+## Architecture Overview
 
-- Init → Lock/Unlock → Logout (drops instance). Memento pattern for state resurrection.
+Monorepo crates organized in **four architectural layers**:
 
-**Storage**
+### 1. Foundation Layer
 
-- Consuming apps use `HashMap<UserId, PasswordManagerClient>`.
+- **bitwarden-crypto**: Cryptographic primitives and protocols, key store for securely working with
+  keys held in memory.
+- **bitwarden-state**: Type-safe Repository pattern for SDK state (client-managed vs SDK-managed)
+- **bitwarden-threading**: ThreadBoundRunner for !Send types in WASM/GUI contexts (uses PhantomData
+  marker)
+- **bitwarden-ipc**: Type-safe IPC framework with pluggable encryption/transport
+- **bitwarden-error**: Error handling across platforms (basic/flat/full modes via proc macro)
+- **bitwarden-encoding**, **bitwarden-uuid**: Encoding and UUID utilities
 
-## Issues necessitating comments
+### 2. Core Infrastructure
 
-**Auto-generated code changes**
+- **bitwarden-core**: Base Client struct extended by feature crates via extension traits. **DO NOT
+  add functionality here - use feature crates instead.**
+  - **bitwarden-api-api**, **bitwarden-api-identity**: Auto-generated API clients (**DO NOT edit -
+    regenerate from OpenAPI specs**)
 
-- Changes to `bitwarden-api-api/` or `bitwarden-api-identity/` are generally discouraged. These are
-  auto-generated from swagger specs.
+### 3. Feature Implementations
 
-**Secrets in logs/errors**
+- **bitwarden-pm**: PasswordManagerClient wrapping core Client, exposes sub-clients: `auth()`,
+  `vault()`, `crypto()`, `sends()`, `generators()`, `exporters()`
+  - Lifecycle: Init → Lock/Unlock → Logout (drops instance)
+  - Storage: Apps use `HashMap<UserId, PasswordManagerClient>`
+- **bitwarden-vault**: Vault item models, encryption/decryption and management
+- **bitwarden-collections**: Collection models, encryption/decryption and management
+- **bitwarden-auth**: Authentication (send access tokens)
+- **bitwarden-send**: Encrypted temporary secret sharing
+- **bitwarden-generators**: Password/passphrase generators
+- **bitwarden-ssh**: SSH key generation/import
+- **bitwarden-exporters**: Vault export/import with multiple formats
+- **bitwarden-fido**: FIDO2 two-factor authentication
 
-- Do not log keys, passwords, or vault data in logs or error paths. Redact sensitive data.
+### 4. Cross-Platform Bindings
 
-**Business logic in WASM**
+- **bitwarden-uniffi**: Mobile bindings (Swift/Kotlin) via UniFFI
+  - Structs: `#[cfg_attr(feature = "uniffi", derive(uniffi::Record))]`
+  - Enums: `#[cfg_attr(feature = "uniffi", derive(uniffi::Enum))]`
+  - Include `uniffi::setup_scaffolding!()` in lib.rs
+- **bitwarden-wasm-internal**: WebAssembly bindings (**thin bindings only - no business logic**)
+  - Structs: `#[derive(Serialize, Deserialize)]` with
+    `#[cfg_attr(feature = "wasm", derive(Tsify), tsify(into_wasm_abi, from_wasm_abi))]`
 
-- `bitwarden-wasm-internal` contains only thin bindings. Move business logic to feature crates.
+## Critical Patterns & Rules
 
-**Unsafe without justification**
+### Cryptography (bitwarden-crypto)
 
-- Any `unsafe` block needs a comment explaining why it's safe and what invariants are being upheld.
+- **DO NOT modify** without careful consideration - backward compatibility is critical
+- **KeyStoreContext**: Never hold across await points
+- Naming: `derive_` for deterministic key derivation, `make_` for non-deterministic generation
+- Use `bitwarden_crypto::safe` module first (password-protected key envelope, data envelope) instead
+  of more low-level primitives
+- IMPORTANT: Use constant time equality checks
+- Do not expose low-level / hazmat functions from the crypto crate.
+- Do not expose key material from the crypto crate, use key references in the key store instead
 
-**Changes to `bitwarden-crypto/` core functionality**
+### State Management (bitwarden-state)
 
-- Generally speaking, this crate should not be modified. Changes need a comment explaining why.
+- **Client-managed**: App and SDK share data pool (requires manual setup)
+- **SDK-managed**: SDK exclusively handles storage (migration-based, ordering is critical)
+- Register types with `register_repository_item!` macro
+- Type safety via TypeId-based type erasure with runtime downcast checks
 
-**New crypto algorithms or key derivation**
+### Threading (bitwarden-threading)
 
-- Detailed description, review and audit trail required. Document algorithm choice rationale and
-  test vectors.
+- Use ThreadBoundRunner for !Send types (WASM contexts, GUI handles, Rc<T>)
+- Pins state to thread via spawn_local, tasks via mpsc channel
+- PhantomData<\*const ()> for !Send marker (zero-cost)
 
-**Encryption/decryption modifications**
+### Error Handling (bitwarden-error-macro)
 
-- Verify backward compatibility. Existing encrypted data must remain decryptable.
+- Three modes: **basic** (string), **flat** (variant), **full** (structure)
+- Generates FlatError trait, WASM bindings, TypeScript interfaces, UniFFI errors
+- Conditional code generation via cfg! for WASM
 
-**Breaking serialization**
+### Security Requirements
 
-- Backward compatibility required. Users must decrypt vaults from older versions.
+- **Never log** keys, passwords, or vault data in logs or error paths
+- **Redact sensitive data** in all error messages
+- **Unsafe blocks** require comments explaining safety and invariants
+- **Encryption/decryption changes** must maintain backward compatibility (existing encrypted data
+  must remain decryptable)
+- **Breaking serialization** strongly discouraged - users must decrypt vaults from older versions
 
-**Breaking API changes**
+### API Changes
 
-- Document migration path for clients.
+- **Breaking changes**: Automated detection via cross-repo workflow (see commit 9574dcc1)
+- TypeScript compilation tested against `clients` repo on PR
+- Document migration path for clients
+
+## Development Workflow
+
+**Build & Test:**
+
+- `cargo check --all-features --all-targets` - Quick validation
+- `cargo test --workspace --all-features` - Full test suite
+
+**Format & Lint:**
+
+- `cargo +nightly fmt --workspace` - Code formatting
+- Use `cargo clippy` to lint code and catch common mistakes
+
+**WASM Testing:**
+
+- `cargo test --target wasm32-unknown-unknown --features wasm -p bitwarden-error -p bitwarden-threading -p bitwarden-uuid` -
+  WASM-specific tests
 
 ## References
 
@@ -66,3 +130,4 @@ PasswordManagerClient ([bitwarden-pm](crates/bitwarden-pm/src/lib.rs)) wraps
 - [Code Style](https://contributing.bitwarden.com/contributing/code-style/)
 - [Security Whitepaper](https://bitwarden.com/help/bitwarden-security-white-paper/)
 - [Security Definitions](https://contributing.bitwarden.com/architecture/security/definitions)
+- [Rust 2024 Edition Guide](https://doc.rust-lang.org/edition-guide/rust-2024/)

crates/bitwarden-error-macro/CLAUDE.md

@@ -0,0 +1,27 @@
+# bitwarden-error-macro
+
+Read any available documentation: [README.md](./README.md) for architecture,
+[examples/](./examples/) for usage patterns, and [tests/](./tests/) for integration tests.
+
+## Three Modes
+
+Specified via `#[bitwarden_error(mode)]`:
+
+- **basic**: String errors only—converts to JS string via `ToString`
+- **flat**: Variant-based—generates `FlatError` trait, TypeScript union types
+- **full**: Structure-based—uses `Serialize` + `tsify` for full error details
+
+Generates platform-specific bindings: `From<T> for JsValue` (WASM), TypeScript interfaces,
+`uniffi::Error` (mobile).
+
+## Critical Rules
+
+**Requires `thiserror`**: All error enums must derive `#[derive(Error)]` from thiserror crate.
+
+**Conditional generation**: WASM bindings only generated when `wasm` feature enabled—check with
+`cfg!(feature = "wasm")`.
+
+**Unsupported**: `full` mode with `export_as` parameter is not supported.
+
+**Debug with `cargo expand`**: If macro output is unclear, use `cargo expand` to inspect generated
+code.

crates/bitwarden-ipc/CLAUDE.md

@@ -0,0 +1,18 @@
+# bitwarden-ipc
+
+Read any available documentation: [README.md](./README.md) for architecture,
+[examples/](./examples/) for usage patterns, and [tests/](./tests/) for integration tests.
+
+## Critical Rules
+
+**RPC types require serialization**: All `RpcRequest` and response types must implement
+`Serialize + DeserializeOwned`.
+
+**Subscribe before sending**: Call `subscribe()` before `send()` to prevent race conditions where
+messages arrive before subscription.
+
+**Call `start()` first**: Client must be started via `start()` before subscribing or
+`SubscribeError::NotStarted` is returned.
+
+**Handler name collisions**: Registering multiple handlers with the same `RpcRequest::NAME` causes
+last registration to silently win—no error is raised.

crates/bitwarden-state/CLAUDE.md

@@ -0,0 +1,12 @@
+# bitwarden-state
+
+Read any available documentation: [README.md](./README.md) for architecture,
+[examples/](./examples/) for usage patterns, and [tests/](./tests/) for integration tests.
+
+## Critical Rules
+
+**SDK-managed types require serialization**: Types must implement `Serialize + DeserializeOwned` to
+use SDK-managed storage.
+
+**Initialize database before access**: Call `initialize_database()` before accessing SDK-managed
+repositories or `get_sdk_managed()` returns `DatabaseNotInitialized` error.

crates/bitwarden-threading/CLAUDE.md

@@ -0,0 +1,12 @@
+# bitwarden-threading
+
+Read any available documentation: [README.md](./README.md) for architecture,
+[examples/](./examples/) for usage patterns, and [tests/](./tests/) for integration tests.
+
+## Critical Rules
+
+**Native requires LocalSet**: `tokio::task::spawn_local` panics without LocalSet context—WASM does
+not have this requirement.
+
+**No blocking operations**: Blocking tasks stalls the entire runner since all tasks execute on a
+single thread.