docs(release): document v3.0.0 credential backend changes

- add breaking-change release notes for keychain-first credential storage and legacy plaintext deprecation

- document backend selection env vars and windows powershell setup examples

- update docker/headless auth guidance for env read-only mode

- include merged PR #5 newline-formatting fix in release notes

Signed-off-by: night-slayer18 <samanuaia257@gmail.com>

Author: night-slayer18

README.md

@@ -410,32 +410,37 @@ leetcode/
 
 ## Authentication
 
-This CLI uses cookie-based authentication. To login:
+This CLI uses cookie-based authentication from your LeetCode browser session.
 
 1. Open [leetcode.com](https://leetcode.com) in your browser
 2. Login to your account
 3. Open DevTools (F12) → Application → Cookies → leetcode.com
 4. Run `leetcode login` and paste your `LEETCODE_SESSION` and `csrftoken` values
 
-## Configuration File
-
-Config is stored at `~/.leetcode/config.json`:
-
-```json
-{
-  "credentials": {
-    "session": "...",
-    "csrfToken": "..."
-  },
-  "config": {
-    "language": "java",
-    "editor": "code",
-    "workDir": "/path/to/leetcode",
-    "repo": "https://github.com/username/leetcode-solutions.git"
-  }
-}
+### Credential Backend
+
+- Default backend: system keychain (`keytar`)
+- Explicit encrypted-file backend: set `LEETCODECLI_CREDENTIAL_BACKEND=file`
+- File backend requires `LEETCODECLI_MASTER_KEY`
+- Env read-only mode: set both `LEETCODE_SESSION` and `LEETCODE_CSRF_TOKEN`
+
+If both env vars are present, the CLI uses them directly and `login/logout` run in read-only env mode.
+
+Windows (PowerShell) quick setup:
+
+```powershell
+$env:LEETCODECLI_CREDENTIAL_BACKEND = "keychain"
+# or encrypted file backend:
+# $env:LEETCODECLI_CREDENTIAL_BACKEND = "file"
+# $env:LEETCODECLI_MASTER_KEY = "<your_master_key>"
 ```
 
+### Config File
+
+Workspace config is stored at:
+
+- `~/.leetcode/workspaces/<name>/config.json`
+
 ## Requirements
 
 - Node.js >= 20.0.0
@@ -532,7 +537,7 @@ You can run the CLI using Docker without installing Node.js.
      -v "$HOME/.leetcode:/root/.leetcode" \
      leetcode-cli list
    ```
-   _Note: We mount `~/.leetcode` to persist login credentials and `leetcode` folder to save solution files._
+   _Note: We mount `~/.leetcode` to persist CLI data (workspace config, snapshots, optional file-backend credentials) and `leetcode` folder to save solution files._
 
 ## License
 

docs/commands.md

@@ -43,6 +43,11 @@ See [TUI Guide](tui.md) for complete behavior and screen-specific shortcuts.
 
 Login to LeetCode with browser cookies.
 
+Notes:
+- Default credential backend is system keychain.
+- Set `LEETCODECLI_CREDENTIAL_BACKEND=file` with `LEETCODECLI_MASTER_KEY` for encrypted file mode.
+- If both `LEETCODE_SESSION` and `LEETCODE_CSRF_TOKEN` are set, login runs in read-only env mode.
+
 **Usage**: `leetcode login`
 
 ---
@@ -51,6 +56,9 @@ Login to LeetCode with browser cookies.
 
 Clear stored credentials.
 
+Note:
+- In env auth mode (`LEETCODE_SESSION` + `LEETCODE_CSRF_TOKEN`), unset env vars in your shell to log out.
+
 **Usage**: `leetcode logout`
 
 ---

docs/config.md

@@ -13,6 +13,48 @@ The CLI requires your LeetCode authentication cookies.
    ```
 5. Paste the values.
 
+## Credential Storage
+
+Credential backend is selected via environment variable:
+
+- Default: `LEETCODECLI_CREDENTIAL_BACKEND=keychain` (system keychain)
+- Optional: `LEETCODECLI_CREDENTIAL_BACKEND=file` (encrypted file backend)
+- File backend requires: `LEETCODECLI_MASTER_KEY`
+- Read-only env mode: set both `LEETCODE_SESSION` and `LEETCODE_CSRF_TOKEN`
+
+When env mode is active, `login/logout` do not persist or clear credentials.
+
+## Windows (PowerShell) Examples
+
+Set backend selection:
+
+```powershell
+$env:LEETCODECLI_CREDENTIAL_BACKEND = "keychain"
+```
+
+Use encrypted file backend:
+
+```powershell
+$env:LEETCODECLI_CREDENTIAL_BACKEND = "file"
+$env:LEETCODECLI_MASTER_KEY = "<your_master_key>"
+```
+
+Use env read-only auth mode:
+
+```powershell
+$env:LEETCODE_SESSION = "<session_cookie>"
+$env:LEETCODE_CSRF_TOKEN = "<csrf_cookie>"
+```
+
+Clear env variables:
+
+```powershell
+Remove-Item Env:LEETCODECLI_CREDENTIAL_BACKEND -ErrorAction SilentlyContinue
+Remove-Item Env:LEETCODECLI_MASTER_KEY -ErrorAction SilentlyContinue
+Remove-Item Env:LEETCODE_SESSION -ErrorAction SilentlyContinue
+Remove-Item Env:LEETCODE_CSRF_TOKEN -ErrorAction SilentlyContinue
+```
+
 ## Config Command
 
 Use `leetcode config` to view or modify settings.
@@ -55,7 +97,7 @@ Settings are now stored per-workspace for isolation:
 | Timer       | `~/.leetcode/workspaces/<name>/timer.json`  | Per-workspace |
 | Collab      | `~/.leetcode/workspaces/<name>/collab.json` | Per-workspace |
 | Snapshots   | `~/.leetcode/workspaces/<name>/snapshots/`  | Per-workspace |
-| Credentials | `~/.leetcode/credentials.json`              | Shared        |
+| Credentials | Keychain (default) or `~/.leetcode/credentials.v2.enc.json` (file backend) | Shared |
 | Bookmarks   | `~/.leetcode/bookmarks.json`                | Shared        |
 
 Use `leetcode workspace current` to see which workspace is active.

docs/docker.md

@@ -61,6 +61,22 @@ leetcode submit 1
 
 `-it` is required for TUI mode. The shell function shown above already includes it.
 
+### Authentication in Docker/Headless Environments
+
+System keychain is usually unavailable inside containers, so interactive `leetcode login` is not supported there.
+Use env credentials instead:
+
+```bash
+docker run -it --rm \
+  -e LEETCODE_SESSION=\"<your_session_cookie>\" \
+  -e LEETCODE_CSRF_TOKEN=\"<your_csrf_cookie>\" \
+  -w /root/leetcode \
+  -v \"$(pwd)/leetcode:/root/leetcode\" \
+  nightslayer/leetcode-cli:latest list
+```
+
+When both env vars are set, the CLI runs in read-only env auth mode.
+
 ## Build Locally
 
 If you prefer to build it yourself:

docs/releases.md

@@ -1,5 +1,44 @@
 # Release Notes
 
+## v3.0.0
+
+> **Release Date**: 2026-03-10
+> **Focus**: Credential Backend Overhaul (Keychain-First) + Auth Hardening
+
+### ⚠️ Breaking Changes
+
+- Credential persistence model is now backend-driven and no longer reads legacy plaintext `~/.leetcode/credentials.json`.
+- Existing users with only legacy plaintext credentials must run `leetcode login` again.
+- Default credential backend is now OS keychain (`keytar`).
+
+### 🔐 Security & Auth
+
+- Added deterministic credential backend resolver:
+  - `env-readonly` mode when `LEETCODE_SESSION` and `LEETCODE_CSRF_TOKEN` are both set.
+  - `keychain` backend by default.
+  - Explicit encrypted-file backend via `LEETCODECLI_CREDENTIAL_BACKEND=file` + `LEETCODECLI_MASTER_KEY`.
+- Added typed auth storage status/reason handling across CLI and TUI:
+  - `ENV_PARTIAL`, `KEYCHAIN_UNAVAILABLE`, `KEYCHAIN_ERROR`, `FILE_MISSING_MASTER_KEY`, `FILE_DECRYPT_FAILED`, `LEGACY_CREDENTIALS_IGNORED`.
+- Updated `login`, `logout`, `whoami`, and shared auth checks with consistent remediation messaging.
+
+### ⚙️ Runtime & Platform
+
+- Added Linux keychain prerequisites in CI for deterministic native module builds (`libsecret-1-dev`, `pkg-config`).
+- Updated Docker image build/runtime dependencies for keytar compatibility in Linux containers.
+- Docker/headless guidance now documents env-readonly auth usage.
+
+### 🧪 Testing
+
+- Added dedicated credential-store tests for resolver precedence, reason states, encrypted file read/write, and legacy-ignore behavior.
+- Added CLI and TUI auth tests for env-readonly mode and keychain-unavailable handling.
+
+### 🔧 Additional Merged Fixes
+
+- Included merged PR [#5](https://github.com/night-slayer18/leetcode-cli/pull/5):
+  - **Config file write normalization**: `config` writes now include a trailing newline for POSIX-friendly file formatting.
+
+---
+
 ## v2.4.1
 
 > **Release Date**: 2026-03-08