diff --git a/CLAUDE.md b/CLAUDE.md
index 311e3e7..0478fab 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,14 +9,12 @@ A full-featured password manager web app and browser extension modelled after La
 ## Tech Stack
 
 ### Development (Windows)
-
 - **Backend:** Python 3.12, Flask 3.x
 - **Database:** MySQL 8.x
 - **Frontend:** Vanilla JS (Web Crypto API) + Jinja2 templates
 - **Dev server:** `python run.py`
 
 ### Production (Ubuntu)
-
 - **Web server:** Nginx (reverse proxy, TLS termination)
 - **WSGI server:** Gunicorn
 - **Process manager:** systemd
@@ -41,89 +39,67 @@ Web App            <──> Nginx ──> Gunicorn ──> Flask App  │
 ```
 passkeeper/
 ├── app/
-│   ├── __init__.py          # App factory (blueprints, extensions, CSRF exemptions, security headers)
-│   ├── config.py            # DevelopmentConfig / ProductionConfig (TOTP_ENCRYPTION_KEY, CORS_ORIGINS, RATELIMIT_STORAGE_URI)
+│   ├── __init__.py          # App factory, blueprints, CSRF exemptions, security headers
+│   ├── config.py            # DevelopmentConfig / ProductionConfig
 │   ├── models/
-│   │   ├── user.py                  # User model (Argon2id, TOTP encrypted, ECDH sharing keys, recovery columns)
-│   │   ├── vault_item.py            # VaultItem model (enc_data, iv, enc_name, iv_name — all sensitive fields encrypted)
-│   │   ├── folder.py                # Folder model
-│   │   ├── token_blacklist.py       # JWT revocation on logout (jti + expires_at)
-│   │   ├── shared_item.py           # Cross-user ECDH-encrypted item shares
-│   │   ├── emergency_access.py      # Emergency access grants (state machine)
-│   │   └── audit_log.py             # Server-side audit trail for all CUD actions
+│   │   ├── user.py                  # Argon2id, TOTP encrypted, ECDH keys, recovery
+│   │   ├── vault_item.py            # enc_data, iv, enc_name, iv_name
+│   │   ├── folder.py
+│   │   ├── token_blacklist.py       # JWT revocation (jti + expires_at)
+│   │   ├── shared_item.py           # ECDH-encrypted cross-user shares
+│   │   ├── emergency_access.py      # State machine
+│   │   └── audit_log.py
 │   ├── routes/
-│   │   ├── auth.py          # Register, login, MFA/TOTP, logout, refresh, change-password, delete-account, recovery
-│   │   ├── vault.py         # CRUD vault items (accepts enc_name/iv_name on create/update)
-│   │   ├── folders.py       # CRUD folders
-│   │   ├── sharing.py       # ECDH key exchange + zero-knowledge item sharing
-│   │   └── emergency.py     # Emergency access state machine
+│   │   ├── auth.py          # Register, login, MFA, logout, refresh, change-password, recovery
+│   │   ├── vault.py         # CRUD + GET /export + POST /import
+│   │   ├── folders.py
+│   │   ├── sharing.py
+│   │   └── emergency.py
 │   ├── services/
-│   │   └── auth_service.py  # Argon2id hashing, JWT generation, blacklist, @require_jwt, TOTP encrypt/decrypt
+│   │   └── auth_service.py  # Argon2id, JWT, blacklist, @require_jwt, TOTP encrypt/decrypt
 │   ├── static/
-│   │   ├── css/app.css      # Full responsive stylesheet (phone/tablet/laptop/PC breakpoints)
+│   │   ├── css/app.css      # Full responsive stylesheet; collapsible group styles; tag badge styles
 │   │   └── js/
-│   │       ├── crypto.js    # Web Crypto API: deriveAuthHash, deriveVaultKey, encryptItem, decryptItem,
+│   │       ├── crypto.js    # deriveAuthHash, deriveVaultKey, encryptItem, decryptItem,
 │   │       │                #   encryptName, decryptName, generateSalt
-│   │       ├── auth.js      # Login/register forms + TOTP MFA step + VaultSession
-│   │       ├── recover.js   # Account recovery flow (two-step: verify code → set new password)
-│   │       ├── sharing.js   # ECDH P-256 key generation, encrypt/decrypt for sharing
-│   │       └── vault.js     # Vault UI: all views + sidebar toggle + change-password + recovery + delete-account
-│   │                        #   renderSecurityDashboard is async — runs HIBP k-anonymity checks after sync sections
-│   └── templates/
-│       ├── base.html        # CSP meta, csrf-token meta, viewport meta, no inline scripts/styles
-│       ├── auth/
-│       │   ├── login.html   # Login + MFA step + "Forgot password?" link
-│       │   ├── register.html
-│       │   └── recover.html # Two-step account recovery page
-│       └── vault/
-│           └── index.html   # Sidebar (collapsible), mobile topbar, vault list, modals
-├── extension/               # Browser extension (Manifest V3)
-│   ├── manifest.json        # MV3: permissions, content_scripts, background, action
-│   ├── background.js        # Service worker: badge count, save-credentials relay, SSO sync,
-│   │                        #   KEEPALIVE ping handler, OPEN_VAULT tab opener
+│   │       ├── auth.js      # Login/register + TOTP MFA + VaultSession
+│   │       ├── recover.js
+│   │       ├── sharing.js   # ECDH P-256
+│   │       └── vault.js     # Full vault UI — see "Key Features" below
+│   └── templates/vault/
+│       └── index.html       # Tags field, Auto-Lock setting, Import/Export view + sidebar
+├── extension/
+│   ├── manifest.json          # MV3 (Chrome/Edge); Ctrl+Shift+L keyboard shortcut
+│   ├── manifest.firefox.json  # MV2 (Firefox)
+│   ├── background.js          # Chrome SW: badges, pending-save "!" badge, CLEAR_SAVE_BADGE
+│   ├── background.firefox.js  # Firefox: in-memory session shim, setTimeout idle lock
 │   ├── shared/
-│   │   └── crypto.js        # Same PBKDF2+AES-GCM logic; extractable vault key for session storage;
-│   │                        #   encryptName / decryptName helpers for item name encryption
+│   │   ├── crypto.js            # PBKDF2+AES-GCM; encryptName/decryptName; extractable key
+│   │   └── browser-polyfill.js  # chrome=browser alias for Firefox content scripts
 │   ├── popup/
-│   │   ├── popup.html       # Login → MFA → Unlock-only → Vault → Generator → Add Item views
-│   │   ├── popup.css        # Includes generator styles, save-modal overlay, pk-flyout context menu
-│   │   └── popup.js         # Auth, vault fetch/decrypt (decrypts enc_name), tabs, autofill trigger,
-│   │                        #   inline password generator (fully CSPRNG via _cryptoRandInt),
-│   │                        #   save-prompt modal, copy-username button, three-dot flyout menu,
-│   │                        #   SSO, service-worker keepalive, relevant-tab domain filter
+│   │   ├── popup.html  # Tabs: All relevant / All items / Favorites / Recents
+│   │   ├── popup.css   # .pk-group-* collapsible styles; .pk-tag badge; .pk-flyout menu
+│   │   └── popup.js    # Vault+folder fetch; collapsible groups; Favorites tab;
+│   │                   #   tag display; clipboard auto-clear; CSPRNG generator;
+│   │                   #   save badge clear; three-dot flyout; copy-username button
 │   ├── content/
-│   │   └── content.js       # Form detection; _isLikelyUsernameField heuristic (autocomplete/name/id scoring);
-│   │                        #   injects PK icon into username AND password fields only;
-│   │                        #   debounced input handler (150ms); MutationObserver guards against
-│   │                        #   re-triggering on extension's own DOM mutations;
-│   │                        #   _normaliseUrl handles bare domains ("github.com")
+│   │   └── content.js  # _isLikelyUsernameField; _normaliseUrl; debounced input (150ms);
+│   │                   #   MutationObserver guard; vault_items_cs from chrome.storage.session
 │   ├── bridge/
-│   │   └── bridge.js        # SSO bridge (runs on vault domain only): syncs session web↔extension
-│   ├── icons/               # Generated by make_icons.py (Pillow)
-│   │   ├── icon16.png
-│   │   ├── icon48.png
-│   │   └── icon128.png
-│   └── make_icons.py        # Re-run to regenerate icons: python extension/make_icons.py
-├── migrations/
-│   ├── env.py               # Alembic env (Flask-Migrate)
-│   ├── script.py.mako
-│   └── versions/
-│       ├── 71d7158dd3b9_add_audit_log_tables_fix_sharing_public_.py
-│       ├── a1b2c3d4e5f6_encrypt_totp_secret_at_rest.py       # Widens totp_secret + adds totp_iv
-│       ├── b2c3d4e5f6a7_add_account_recovery_columns.py      # Adds recovery_enc_salt + recovery_iv
-│       └── c3d4e5f6a7b8_encrypt_vault_item_name.py           # Adds enc_name + iv_name to vault_items
+│   │   └── bridge.js   # SSO bridge (vault domain only)
+│   └── icons/
+├── migrations/versions/
+│   ├── 71d7158dd3b9_add_audit_log_tables_fix_sharing_public_.py
+│   ├── a1b2c3d4e5f6_encrypt_totp_secret_at_rest.py
+│   ├── b2c3d4e5f6a7_add_account_recovery_columns.py
+│   └── c3d4e5f6a7b8_encrypt_vault_item_name.py   # adds enc_name + iv_name
 ├── scripts/
-│   ├── reencrypt_totp_secrets.py   # One-time migration: encrypt existing plaintext TOTP secrets
-│   ├── backup_db.sh                # Automated MySQL backup (gzip, 30-day retention)
-│   ├── backup.cron                 # Crontab entry for daily 2 AM backup
-│   ├── passkeeper-logrotate        # logrotate config for Gunicorn logs
-│   ├── passkeeper-nginx.conf       # Hardened Nginx config (HSTS, rate limiting, upstream retry)
-│   └── passkeeper.service          # Hardened systemd unit (watchdog, preload, sandboxing)
-├── reset_db.py              # Drop + recreate all tables (dev only, handles FK checks)
+│   ├── reencrypt_totp_secrets.py
+│   ├── backup_db.sh / backup.cron / passkeeper-logrotate
+│   ├── passkeeper-nginx.conf / passkeeper.service
+├── reset_db.py
 ├── requirements.txt
-├── wsgi.py                  # Gunicorn entry point
-├── run.py                   # Dev entry point
-├── .env
+├── wsgi.py / run.py
 └── CLAUDE.md
 ```
 
@@ -136,204 +112,143 @@ passkeeper/
 CREATE TABLE users (
     id                       INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
     email                    VARCHAR(255) UNIQUE NOT NULL,
-    master_hash              VARCHAR(255) NOT NULL,   -- Argon2id hash of client-derived PBKDF2 auth_hash
-    enc_key_salt             VARCHAR(64) NOT NULL,    -- Random 16-byte salt (base64), returned on login
-    created_at               DATETIME DEFAULT NOW(),
-    last_login               DATETIME,
-    -- TOTP / MFA (secret AES-256-GCM encrypted at rest)
-    totp_secret              VARCHAR(255),            -- AES-256-GCM ciphertext of base32 secret (base64)
-    totp_iv                  VARCHAR(64),             -- base64 12-byte GCM nonce for totp_secret
+    master_hash              VARCHAR(255) NOT NULL,   -- Argon2id(authHash)
+    enc_key_salt             VARCHAR(64) NOT NULL,
+    created_at / last_login  DATETIME,
+    totp_secret              VARCHAR(255),  -- AES-256-GCM ciphertext
+    totp_iv                  VARCHAR(64),
     totp_enabled             TINYINT(1) DEFAULT 0,
-    -- ECDH P-256 sharing keypair
-    sharing_public_key       VARCHAR(128),            -- Raw uncompressed point (65 bytes), base64, plaintext
-    sharing_private_key_enc  TEXT,                    -- JWK, AES-256-GCM encrypted with vault key
-    sharing_private_key_iv   VARCHAR(64),             -- base64 12-byte nonce for private key encryption
-    -- Account recovery
-    recovery_enc_salt        VARCHAR(128),            -- enc_key_salt re-encrypted with recovery key (base64)
-    recovery_iv              VARCHAR(64)              -- base64 12-byte nonce for recovery_enc_salt
+    sharing_public_key       VARCHAR(128),
+    sharing_private_key_enc  TEXT,
+    sharing_private_key_iv   VARCHAR(64),
+    recovery_enc_salt        VARCHAR(128),
+    recovery_iv              VARCHAR(64)
 );
 
--- Folders
-CREATE TABLE folders (
+-- Vault Items
+CREATE TABLE vault_items (
     id         INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
     user_id    INT UNSIGNED NOT NULL,
-    name       VARCHAR(128) NOT NULL,
-    FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE
-);
-
--- Vault Items (all sensitive fields AES-256-GCM encrypted client-side)
-CREATE TABLE vault_items (
-    id           INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
-    user_id      INT UNSIGNED NOT NULL,
-    folder_id    INT UNSIGNED,
-    item_type    VARCHAR(20) NOT NULL DEFAULT 'password',  -- plain string, not ENUM
-    name         VARCHAR(255) NOT NULL,                    -- non-sensitive server label (item type only)
-    enc_data     TEXT NOT NULL,                            -- base64 AES-256-GCM ciphertext of item payload
-    iv           VARCHAR(64) NOT NULL,                     -- base64 12-byte GCM nonce for enc_data
-    enc_name     TEXT,                                     -- base64 AES-256-GCM ciphertext of item name
-    iv_name      VARCHAR(64),                              -- base64 12-byte GCM nonce for enc_name
-    created_at   DATETIME DEFAULT NOW(),
-    updated_at   DATETIME DEFAULT NOW() ON UPDATE NOW(),
+    folder_id  INT UNSIGNED,
+    item_type  VARCHAR(20) NOT NULL DEFAULT 'password',
+    name       VARCHAR(255) NOT NULL,  -- server label only (item type string)
+    enc_data   TEXT NOT NULL,          -- AES-256-GCM ciphertext of payload + tags
+    iv         VARCHAR(64) NOT NULL,
+    enc_name   TEXT,                   -- AES-256-GCM ciphertext of item name (nullable)
+    iv_name    VARCHAR(64),
+    created_at DATETIME DEFAULT NOW(),
+    updated_at DATETIME DEFAULT NOW() ON UPDATE NOW(),
     FOREIGN KEY (user_id) REFERENCES users(id) ON DELETE CASCADE,
     FOREIGN KEY (folder_id) REFERENCES folders(id) ON DELETE SET NULL
 );
-
--- Token Blacklist (JWT revocation)
-CREATE TABLE token_blacklist (
-    id         INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
-    jti        VARCHAR(36) UNIQUE NOT NULL,
-    user_id    INT UNSIGNED NOT NULL,
-    expires_at DATETIME NOT NULL,
-    INDEX (jti), INDEX (expires_at)
-);
-
--- Shared Items (ECDH zero-knowledge sharing)
-CREATE TABLE shared_items (
-    id              INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
-    item_id         INT UNSIGNED NOT NULL,
-    owner_id        INT UNSIGNED NOT NULL,
-    recipient_email VARCHAR(255) NOT NULL,
-    recipient_id    INT UNSIGNED,
-    item_name       VARCHAR(255) NOT NULL,  -- plaintext display name for share inbox
-    item_type       VARCHAR(20) NOT NULL,
-    enc_data        TEXT NOT NULL,
-    iv              VARCHAR(64) NOT NULL,
-    accepted        TINYINT(1) DEFAULT 0,
-    created_at      DATETIME DEFAULT NOW(),
-    FOREIGN KEY (item_id) REFERENCES vault_items(id) ON DELETE CASCADE
-);
-
--- Emergency Access
-CREATE TABLE emergency_access (
-    id                   INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
-    grantor_id           INT UNSIGNED NOT NULL,
-    grantee_email        VARCHAR(255) NOT NULL,
-    grantee_id           INT UNSIGNED,
-    wait_days            INT NOT NULL DEFAULT 7,
-    status               VARCHAR(20) NOT NULL DEFAULT 'invited',
-    request_initiated_at DATETIME,
-    enc_vault            TEXT,
-    created_at           DATETIME DEFAULT NOW(),
-    FOREIGN KEY (grantor_id) REFERENCES users(id) ON DELETE CASCADE,
-    FOREIGN KEY (grantee_id) REFERENCES users(id) ON DELETE SET NULL
-);
-
--- Audit Logs
-CREATE TABLE audit_logs (
-    id            INT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
-    user_id       INT UNSIGNED NOT NULL,
-    action        VARCHAR(64) NOT NULL,
-    resource_type VARCHAR(64) NOT NULL,
-    resource_id   INT UNSIGNED,
-    detail        VARCHAR(512),
-    ip_address    VARCHAR(45),
-    created_at    DATETIME NOT NULL,
-    INDEX (user_id), INDEX (created_at)
-);
+-- (folders, token_blacklist, shared_items, emergency_access, audit_logs — unchanged)
 ```
 
 ---
 
+## Migration History
+
+| Revision | Description |
+|---|---|
+| `71d7158dd3b9` | Add audit_logs; fix sharing_public_key type |
+| `a1b2c3d4e5f6` | Encrypt TOTP secret at rest |
+| `b2c3d4e5f6a7` | Add account recovery columns |
+| `c3d4e5f6a7b8` | Add enc_name + iv_name to vault_items |
+
+---
+
 ## Security Model
 
 - **Zero-knowledge:** master password never sent to server
-  - `authHash = PBKDF2(masterPassword, email, 100_000 iter)` — sent to server for auth only
-  - `vaultKey = PBKDF2(masterPassword, enc_key_salt, 600_000 iter)` — stays in browser memory only
-  - All vault data (payload + item name) encrypted client-side (AES-256-GCM) before sending to server
-- **Item name encryption:** `enc_name`/`iv_name` store the AES-256-GCM ciphertext of the item name. The server's plaintext `name` column holds only the item type (e.g. `"password"`) as a non-sensitive audit label. Legacy items without `enc_name` fall back to `name` transparently.
-- **Server-side:** Argon2id hash of the client-derived `authHash` (double-hashed for depth)
-- **JWT:** HS256, access token 15 min, refresh token 7 days, unique JTI per token
-- **JWT blacklist:** on logout both tokens are blacklisted by JTI; refresh rotates tokens
-- **MFA:** TOTP (pyotp), secret stored AES-256-GCM encrypted in `users.totp_secret`/`totp_iv`
-- **Sharing:** ECDH P-256 — shared secret derived client-side, re-encrypts item plaintext
-- **Emergency access:** same ECDH re-encryption; wait timer enforced server-side
-- **CSRF:** Flask-WTF on page-serving routes; API blueprints CSRF-exempt (JWT bearer auth)
-- **Rate limiting:** Flask-Limiter (Redis-backed in production); Nginx dual-zone as second layer
-- **HTTP security headers:** HSTS, X-Frame-Options, X-Content-Type-Options, Referrer-Policy, Permissions-Policy, CSP via `@app.after_request`
-- **Password generator (extension):** Fully CSPRNG — `_cryptoRandInt()` uses rejection-sampling with `crypto.getRandomValues()`. `Math.random()` is never called anywhere in the generator.
-- **Decrypted vault data in extension:** Stored in `chrome.storage.session` only (memory-only, cleared on browser close). Never written to `chrome.storage.local`.
-- **Breach detection:** Security dashboard runs HaveIBeenPwned k-anonymity checks — only the first 5 chars of each password's SHA-1 hash are transmitted. Passwords never leave the browser.
+  - `authHash = PBKDF2(masterPassword, email, 100k iter)` → auth only
+  - `vaultKey = PBKDF2(masterPassword, enc_key_salt, 600k iter)` → browser memory only
+  - All vault data (payload + name + tags) encrypted client-side (AES-256-GCM)
+- **Item name:** `enc_name`/`iv_name`; server `name` column = item type only
+- **Tags:** `plain.tags: string[]` inside `enc_data`; server never sees them
+- **Argon2id:** double-hashes `authHash` server-side
+- **JWT:** HS256, 15 min access / 7 day refresh, JTI blacklisted on logout
+- **MFA:** TOTP secret AES-256-GCM encrypted at rest
+- **Sharing:** ECDH P-256 zero-knowledge re-encryption
+- **Password generator:** fully CSPRNG (`_cryptoRandInt` rejection-sampling)
+- **Decrypted vault data:** `chrome.storage.session` only — never to disk
+- **Clipboard auto-clear:** 30 s after any password/username copy (web + extension)
+- **Breach detection:** HIBP k-anonymity — only 5-char SHA-1 prefix transmitted
 
 ---
 
-## Extension Storage Architecture — Critical Rules
+## Extension Storage Architecture
 
-### Storage area decision table
-
-| Data | Where stored | Why |
+| Data | Storage | Reason |
 |---|---|---|
-| `access_token`, `vault_key_jwk`, `vault_items`, `vault_items_cs` | `chrome.storage.session` | Memory-only, cleared on browser close. Decrypted data must never persist to disk. |
-| `refresh_token`, `enc_key_salt`, `pending_save`, `save_blocklist`, `idle_lock_seconds` | `chrome.storage.local` | Persists across browser restarts and SW termination. |
+| `access_token`, `vault_key_jwk`, `vault_items`, `vault_items_cs` | `chrome.storage.session` | Memory-only, cleared on browser close |
+| `refresh_token`, `enc_key_salt`, `pending_save`, `save_blocklist`, `idle_lock_seconds` | `chrome.storage.local` | Persists across restarts |
+| Web-app session timeout | `localStorage` (`web_idle_minutes`) | Per-browser preference |
 
-### `vault_items_cs` is in `chrome.storage.session`, NOT `chrome.storage.local`
+### Critical: `vault_items_cs` is in `session`, NOT `local`
+Requires Chrome 111+. `content.js` `onChanged` listener watches `area === 'session'`. Do not revert — reverting persists decrypted passwords to disk.
 
-As of the current codebase, `vault_items_cs` (the decrypted vault cache for content scripts) is written to **`chrome.storage.session`**. This is a deliberate security decision — decrypted passwords must never be persisted to disk.
-
-**Minimum Chrome version required: 111 (March 2023).** `chrome.storage.session` is not readable by content scripts on Chrome ≤ 110. The `storage.onChanged` listener in `content.js` watches `area === 'session'`.
-
-> ⚠️ **The original CLAUDE.md stated `vault_items_cs` lives in `chrome.storage.local`. That is no longer correct.** If you see it reverting to `local`, that is a regression — revert it.
-
-### `chrome.storage.onChanged` area guard
-
-```js
-chrome.storage.onChanged.addListener(function(changes, area) {
-  if (area === 'session' && changes.vault_items_cs) {  // 'session', not 'local'
-    ...
-  }
-});
-```
-
-### `pending_save` must remain in `chrome.storage.local`
-
-`chrome.storage.session` is wiped when the MV3 service worker is killed (within seconds of inactivity). `pending_save` stays in `local` so the save prompt survives SW restarts.
+### Pending-save badge
+`background.js` sets a red `"!"` badge on `SAVE_CREDENTIALS`. Cleared via `CLEAR_SAVE_BADGE` when user acts on the save prompt in the popup.
 
 ---
 
-## Key Implementation Decisions & Gotchas
+## Key Implementation Details
 
-### Item name is encrypted client-side (`enc_name` / `iv_name`)
+### Vault item tags
+- Stored as `plain.tags: string[]` inside `enc_data`. No schema change ever needed.
+- **Web app:** `_parseTags(str)` → comma-split, lowercase, dedup, sort. `_allTags()` collects across all items. `renderTagList()` builds sidebar. Tags field in modal has live badge preview.
+- **Extension:** `.pk-tag` badges below item subtitle. Favorites tab = items where `tags.includes('favorite')`. Favorited items show gold ★ in site label.
+- To favourite an item: add tag `favorite` in the web app edit modal.
 
-The `name` column in `vault_items` is **not** sensitive — it stores only the item type string (e.g. `"password"`) as a server-side audit label. The real display name is stored as AES-256-GCM ciphertext in `enc_name` with nonce `iv_name`.
+### Collapsible folder groups
+- **Web app:** `_collapsedGroups` Set persists state across re-renders. Header shows name + count badge + chevron (▼/▶). Click toggles and re-renders.
+- **Extension:** only on "All items" tab. `_folders` fetched in parallel with vault. `_collapsedFolders` Set. `folderName(id)` resolves to display name with `(none)` fallback.
 
-**On load:** `loadVault()` / `fetchAndDecryptVault()` decrypt `enc_name` after decrypting `enc_data` and override `item.name` with the plaintext. Legacy items without `enc_name` use the server's `name` field as fallback — no migration of existing rows required.
+### Import / Export
+- **Encrypted JSON export:** `GET /api/vault` → versioned envelope → download. Zero-knowledge.
+- **CSV export:** decrypt client-side → `name, url, username, password, notes`.
+- **JSON import:** sends encrypted blobs to `POST /api/vault/import` directly.
+- **CSV import:** parses Chrome / Bitwarden / 1Password formats; encrypts client-side before POSTing.
+- Both endpoints write audit logs: `vault_item.export`, `vault_item.import`.
 
-**On save:** `handleFormSubmit()` (web app) and `addItemToVault()` / `saveCredential()` (extension) call `Crypto.encryptName(vaultKey, name)` / `ExtCrypto.encryptName(vaultKey, name)` before POSTing, sending `enc_name` + `iv_name` alongside `enc_data` + `iv`.
+### Web-app session timeout
+- `_startWebIdleTracking()` called at end of `init()`. Listens to `mousemove`, `mousedown`, `keydown`, `touchstart`, `scroll`.
+- On timeout: `VaultSession.clear()` → unlock overlay → toast.
+- Stored in `localStorage` as `web_idle_minutes`. Default 15 min. Options: Never/5/10/15/30/60.
+- Exposed in Account Settings → Auto-Lock (`<select id="web-idle-select">`).
 
-**On password change / recovery:** The re-encryption loops in `auth.py` also update `vault_item.enc_name` / `vault_item.iv_name` when the client sends updated values.
+### Browser history / back-button
+- `switchView(view, { pushState = true })` calls `history.pushState({ view }, '', '#view-name')`.
+- `popstate` listener in `init()` restores view. Direct hash links (`/vault#security`) work.
+- `Vault.switchToImportExport()` exposed on public return object for sidebar `<li onclick>` fallback.
 
-**API contract:** `POST /api/vault` and `PUT /api/vault/<id>` now accept optional `enc_name` and `iv_name` fields. The `name` field is still required (used as the server-side label).
+### Clipboard auto-clear
+- Web app: `copyToClipboard()` uses `_clipboardClearTimer` setTimeout 30s → `writeText('')`.
+- Extension: `_copyWithAutoClear()` same pattern. Applied to password, username, and flyout copies.
 
-### Password generator is fully CSPRNG
+### Missing 2FA warning
+- Security dashboard "No 2FA Saved" section: password items with URL but no `totp_uri`.
+- Uses existing `extractTotpSecret()` and `makeSection()`.
 
-`generatePassword()` in `extension/popup/popup.js` uses `_cryptoRandInt(max)` for all random selection:
+### Security score age penalty fix
+- `old` only includes items that are **also weak or reused** (`weakOrReusedIds.has(i.id)`).
+- Strong unique unchanged passwords no longer penalised.
 
-```js
-function _cryptoRandInt(max) {
-  // Rejection sampling — no modulo bias.
-  const limit = Math.floor(0x100000000 / max) * max;
-  const buf = new Uint32Array(1);
-  do { crypto.getRandomValues(buf); } while (buf[0] >= limit);
-  return buf[0] % max;
-}
-```
+### Keyboard shortcut
+- `manifest.json`: `commands._execute_action`, `Ctrl+Shift+L` / `Cmd+Shift+L`.
+- `manifest.firefox.json`: `_execute_browser_action`.
+- Customisable at `chrome://extensions/shortcuts`.
 
-This replaces `Math.floor(Math.random() * n)` which was used in the required-character selection and Fisher-Yates shuffle steps. `Math.random()` is not called anywhere in the generator.
+### Firefox compatibility
+| File | Purpose |
+|---|---|
+| `manifest.firefox.json` | MV2: `browser_action`, `background.scripts` |
+| `background.firefox.js` | In-memory session shim, `setTimeout` idle lock, `browserAction` API |
+| `shared/browser-polyfill.js` | `chrome = browser` alias for content scripts |
 
-### `_isLikelyUsernameField()` — credential field detection heuristic
-
-`findUsernameField()` in `content.js` no longer accepts any `input[type="text"]` preceding the password field. It scores candidates via `_isLikelyUsernameField()`:
-
-1. **Definite YES:** `autocomplete="username"` or `"email"` or `"tel"`
-2. **Definite NO:** Non-credential `autocomplete` values (`name`, `given-name`, `organization`, `search`, etc.)
-3. **Keyword scan YES:** `name`, `id`, `placeholder`, or `aria-label` contain `user|email|mail|login|phone|tel|mobile|account`
-4. **Otherwise:** field is not decorated
-
-`input[type="email"]` and `input[type="tel"]` are always accepted without scoring.
-
-### `_normaliseUrl()` — bare-domain URL matching
-
-Both `content.js` and `popup.js` include a `_normaliseUrl()` helper that prepends `https://` to URLs that lack a scheme before passing them to `new URL()`. This prevents silent match failures for vault items stored with bare domains (e.g. `"github.com"` instead of `"https://github.com"`).
+Load in Firefox: `about:debugging` → This Firefox → Load Temporary Add-on → `manifest.firefox.json`.
 
+### `_normaliseUrl()` — bare-domain matching
 ```js
 function _normaliseUrl(raw) {
   if (!raw) return null;
@@ -343,277 +258,138 @@ function _normaliseUrl(raw) {
   return 'https://' + s;
 }
 ```
+In both `content.js` and `popup.js`. Prevents silent match failures for bare domains.
 
-### MutationObserver guards against extension's own DOM mutations
+### `_isLikelyUsernameField()` — credential field heuristic
+1. **YES:** `autocomplete="username|email|tel"`
+2. **NO:** non-credential autocomplete (`name`, `organization`, `search`, etc.)
+3. **YES:** `name/id/placeholder/aria-label` matches `user|email|mail|login|phone|tel|mobile|account`
+4. **Otherwise:** not decorated
 
-The `MutationObserver` in `content.js` inspects every mutation before calling `decorateFields()`. If every added/removed node carries a `__pk` class or id prefix, the callback returns early — preventing re-decoration loops on SPAs triggered by the extension injecting or removing its own dropdown or icon buttons.
+### MutationObserver guard
+Inspects added/removed nodes — if all carry `__pk` prefix, returns early. Prevents re-decoration loops when the extension injects/removes its own UI.
 
-### `showDropdown` is debounced on `input` events
+### `showDropdown` debounced 150ms on `input`
+`_debounce(fn, ms)` helper. `focus` listener remains instant.
 
-The `input` event listener on decorated fields wraps `showDropdown` with a 150 ms debounce via `_debounce()`. The `focus` listener remains instant. This eliminates visible lag on large vaults when the user types quickly.
-
-### Three-dot menu is now a proper flyout
-
-The `data-menu` button in the popup renders a `.pk-flyout` div anchored below the button. Menu items are built dynamically from what the item has — "Open URL" only if `plain.url` exists, etc. Styled via `.pk-flyout` / `.pk-flyout-item` in `popup.css`. Closes on any outside click.
-
-### Copy-username button is a dedicated action
-
-A `data-copy-user` button with a person SVG icon appears at the left of the action row for any item with a username. This replaces the previous behaviour where the three-dot button silently copied the username on click.
-
-### HaveIBeenPwned breach detection
-
-`renderSecurityDashboard()` in `vault.js` is now `async`. After rendering the synchronous sections (Weak / Reused / Old), it fires parallel HIBP API calls for every password item via `checkHibp(password)`:
-
-```js
-async function checkHibp(password) {
-  const hashHex = /* SHA-1 of password via crypto.subtle */;
-  const prefix = hashHex.slice(0, 5);
-  const suffix = hashHex.slice(5);
-  const res = await fetch(`https://api.pwnedpasswords.com/range/${prefix}`, {
-    headers: { 'Add-Padding': 'true' },
-  });
-  // parse response, find matching suffix, return breach count
-}
-```
-
-Only the first 5 hex characters of the SHA-1 hash are sent. Passwords never leave the browser. Network errors fail safe (return 0, do not block UI). The HIBP section renders progressively after the synchronous sections.
-
-### `item_type` must be `VARCHAR(20)`, NOT `db.Enum(ItemType)`
-
-Using `db.Enum(ItemType)` with a `str`-based Python enum caused SQLAlchemy to lazy-load the column back as a raw string after commit, making `self.item_type.value` raise `AttributeError`. Use `db.String(20)`.
-
-### `INTEGER(unsigned=True)` requires MySQL dialect type
-
-```python
-from sqlalchemy.dialects.mysql import INTEGER
-db.Column(INTEGER(unsigned=True), ...)
-```
-
-### All datetimes are naive UTC (`datetime.utcnow()`)
-
-Do NOT mix in `datetime.now(timezone.utc)` — mixing causes comparison failures in token blacklist and emergency access wait-timer checks.
-
-### AuditLog must flush before log, then commit together
+### Three-dot flyout menu
+`.pk-flyout` div anchored below button. Dynamic items: Open URL / Copy username / Copy password. Closes on outside click.
 
+### AuditLog pattern
 ```python
 db.session.add(item)
-db.session.flush()          # populates item.id
+db.session.flush()   # populates item.id
 AuditLog.log(user_id=..., action='vault_item.create', resource_id=item.id, ...)
-db.session.commit()         # commits both atomically
+db.session.commit()  # atomic
 ```
+For deletes: capture `id` and `name` before flush.
 
-For deletes, capture `id` and `name` before the delete flush.
-
-### Extension vault key must be extractable
-
-`extension/shared/crypto.js` uses `extractable: true` so the vault key can be serialised as JWK and stored in `chrome.storage.session`. The web app uses `extractable: false`.
-
-### JWT `sub` claim must be a string (PyJWT 2.x)
-
-Always convert: `'sub': str(user_id)` when generating tokens; `int(payload['sub'])` when reading back.
-
-### TOTP secrets encrypted at rest (server-side)
-
-`totp_secret` stores AES-256-GCM ciphertext; `totp_iv` stores the nonce. Encrypted/decrypted exclusively by `auth_service.encrypt_totp_secret()` / `auth_service.decrypt_totp_secret()`. Generating the key:
-
-```bash
-python -c "import secrets; print(secrets.token_hex(32))"
-```
-
-### Extension SSO bridge
-
-`bridge.js` runs on `pwkeeper.ngodanguyen.tech` only and syncs sessions bidirectionally between the web app and the extension. See the original CLAUDE.md for the full bridge flow.
-
-### Autofill uses native HTMLInputElement setter for framework compatibility
-
-```js
-const nativeSet = Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value')?.set;
-if (nativeSet) nativeSet.call(el, value);
-el.dispatchEvent(new Event('input', { bubbles: true }));
-el.dispatchEvent(new Event('change', { bubbles: true }));
-```
-
-### `reset_db.py` for schema changes (Windows, no flask db CLI)
-
-```bash
-python reset_db.py
-```
-
-Production schema changes: `flask db upgrade`.
+### Common gotchas
+- `item_type`: use `db.String(20)`, not `db.Enum(ItemType)` — enum lazy-load breaks `.value`
+- `INTEGER(unsigned=True)`: requires `from sqlalchemy.dialects.mysql import INTEGER`
+- All datetimes: naive UTC `datetime.utcnow()` — never mix with timezone-aware
+- Extension vault key: `extractable: true` (web app uses `false`)
+- PyJWT `sub`: `str(user_id)` on encode, `int(payload['sub'])` on decode
+- TOTP key generation: `python -c "import secrets; print(secrets.token_hex(32))"`
+- `#vault-list` ID must not be renamed — `vault.js` renders into it directly
 
 ---
 
-## Audit Log System
+## Audit Action Catalog
 
-Every create, edit, and delete action is recorded server-side via `AuditLog.log()`. No sensitive or encrypted values are ever written to the audit log.
-
-### Audit Action Catalog
-
-| Route module   | Action string                      | Trigger                                           |
-| -------------- | ---------------------------------- | ------------------------------------------------- |
-| `auth.py`      | `auth.register`                    | New account created                               |
-| `auth.py`      | `auth.login`                       | Successful password verification                  |
-| `auth.py`      | `auth.login_failed`                | Failed password attempt (known email)             |
-| `auth.py`      | `auth.mfa_enable`                  | TOTP enabled after verification                   |
-| `auth.py`      | `auth.mfa_disable`                 | TOTP disabled after verification                  |
-| `auth.py`      | `auth.mfa_verify`                  | MFA step completed, session tokens issued         |
-| `auth.py`      | `auth.change_password`             | Master password changed, vault re-encrypted       |
-| `auth.py`      | `auth.change_password_failed`      | Password change rejected — wrong current password |
-| `auth.py`      | `auth.delete_account`              | Account permanently deleted                       |
-| `auth.py`      | `auth.delete_account_failed`       | Deletion rejected — wrong password                |
-| `auth.py`      | `auth.recovery_setup`              | Recovery code configured                          |
-| `auth.py`      | `auth.recovery_failed`             | Recovery attempt — incorrect code                 |
-| `auth.py`      | `auth.recovery_items_denied`       | Recovery items fetch — incorrect proof            |
-| `auth.py`      | `auth.recovery_success`            | Account recovered, vault re-encrypted             |
-| `vault.py`     | `vault_item.create`                | Vault item created                                |
-| `vault.py`     | `vault_item.update`                | Vault item updated                                |
-| `vault.py`     | `vault_item.delete`                | Vault item deleted                                |
-| `folders.py`   | `folder.create`                    | Folder created                                    |
-| `folders.py`   | `folder.update`                    | Folder renamed                                    |
-| `folders.py`   | `folder.delete`                    | Folder deleted                                    |
-| `sharing.py`   | `sharing_keys.create`              | ECDH keypair stored for first time                |
-| `sharing.py`   | `sharing_keys.update`              | ECDH keypair replaced                             |
-| `sharing.py`   | `shared_item.create`               | Item shared with another user                     |
-| `sharing.py`   | `shared_item.delete`               | Share revoked by owner                            |
-| `sharing.py`   | `shared_item.accept`               | Recipient accepted a share                        |
-| `emergency.py` | `emergency_access.create`          | Emergency access invitation sent                  |
-| `emergency.py` | `emergency_access.delete`          | Emergency access grant removed                    |
-| `emergency.py` | `emergency_access.accept`          | Grantee accepted invitation                       |
-| `emergency.py` | `emergency_access.provide_vault`   | Grantor uploaded encrypted vault snapshot         |
-| `emergency.py` | `emergency_access.request`         | Grantee initiated access request                  |
-| `emergency.py` | `emergency_access.deny`            | Grantor denied pending request                    |
-| `emergency.py` | `emergency_access.vault_retrieved` | Grantee fetched vault after wait elapsed          |
+| Module | Action | Trigger |
+|---|---|---|
+| `auth.py` | `auth.register` | New account |
+| `auth.py` | `auth.login` / `auth.login_failed` | Login success/fail |
+| `auth.py` | `auth.mfa_enable/disable/verify` | TOTP actions |
+| `auth.py` | `auth.change_password` / `auth.change_password_failed` | Password change |
+| `auth.py` | `auth.delete_account` / `auth.delete_account_failed` | Deletion |
+| `auth.py` | `auth.recovery_setup/failed/items_denied/success` | Recovery |
+| `vault.py` | `vault_item.create/update/delete` | CRUD |
+| `vault.py` | `vault_item.export` / `vault_item.import` | Import/Export |
+| `folders.py` | `folder.create/update/delete` | Folder CRUD |
+| `sharing.py` | `sharing_keys.create/update` | ECDH key setup |
+| `sharing.py` | `shared_item.create/delete/accept` | Sharing |
+| `emergency.py` | `emergency_access.*` | All EA state transitions |
 
 ---
 
-## REST API Endpoints
-
-All `/api/vault/*` and `/api/folders/*` routes require `Authorization: Bearer <access_token>`.
+## REST API
 
 ```
-POST   /api/auth/register
-POST   /api/auth/login
-POST   /api/auth/logout
-POST   /api/auth/refresh
-GET    /api/auth/me
-GET    /api/auth/mfa/status
-GET    /api/auth/mfa/setup
-POST   /api/auth/mfa/enable
-POST   /api/auth/mfa/disable
-POST   /api/auth/mfa/verify
-POST   /api/auth/change-password   # { current_auth_hash, new_auth_hash, new_enc_key_salt,
-                                   #   items: [{id, enc_data, iv, enc_name?, iv_name?}] }
+POST   /api/auth/register|login|logout|refresh|recover
+GET    /api/auth/me|mfa/status|mfa/setup|recovery/status|recovery/data|recovery/items
+POST   /api/auth/mfa/enable|disable|verify|change-password|recovery/setup
 DELETE /api/auth/account
-POST   /api/auth/recovery/setup
-GET    /api/auth/recovery/status
-GET    /api/auth/recovery/data
-GET    /api/auth/recovery/items
-POST   /api/auth/recover
 
-GET    /api/vault
-POST   /api/vault                  # { name, item_type, folder_id, enc_data, iv, enc_name?, iv_name? }
+GET    /api/vault                 # list all encrypted items
+POST   /api/vault                 # { name, item_type, folder_id, enc_data, iv, enc_name?, iv_name? }
 GET    /api/vault/<id>
-PUT    /api/vault/<id>             # accepts enc_name, iv_name
+PUT    /api/vault/<id>
 DELETE /api/vault/<id>
+GET    /api/vault/export          # returns encrypted item array
+POST   /api/vault/import          # accepts array; returns { imported, skipped }
 
-GET    /api/folders
-POST   /api/folders
-PUT    /api/folders/<id>
-DELETE /api/folders/<id>
+GET|POST        /api/folders
+PUT|DELETE      /api/folders/<id>
 
-GET    /api/sharing/keys
-POST   /api/sharing/keys
-GET    /api/sharing/public-key
-GET    /api/sharing
-POST   /api/sharing
-DELETE /api/sharing/<id>
-GET    /api/sharing/inbox
-POST   /api/sharing/inbox/<id>/accept
+GET|POST        /api/sharing/keys
+GET             /api/sharing/public-key
+GET|POST        /api/sharing
+DELETE          /api/sharing/<id>
+GET             /api/sharing/inbox
+POST            /api/sharing/inbox/<id>/accept
 
-GET    /api/emergency
-POST   /api/emergency
-DELETE /api/emergency/<id>
-POST   /api/emergency/<id>/accept
-POST   /api/emergency/<id>/provide
-POST   /api/emergency/<id>/request
-POST   /api/emergency/<id>/deny
-GET    /api/emergency/<id>/vault
+GET|POST        /api/emergency
+DELETE          /api/emergency/<id>
+POST            /api/emergency/<id>/accept|provide|request|deny
+GET             /api/emergency/<id>/vault
 ```
 
 ---
 
-## Development Setup (Windows)
+## Development Setup
 
 ```bash
-python -m venv .venv
-.venv\Scripts\activate
+python -m venv .venv && .venv\Scripts\activate
 pip install -r requirements.txt
-# Edit .env: MYSQL_HOST, MYSQL_USER, MYSQL_PASSWORD, MYSQL_DB, SECRET_KEY, JWT_SECRET_KEY, TOTP_ENCRYPTION_KEY
+# .env: MYSQL_*, SECRET_KEY, JWT_SECRET_KEY, TOTP_ENCRYPTION_KEY
 mysql -u root -p -e "CREATE DATABASE passkeeper CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
 python reset_db.py
 python run.py
 ```
 
----
-
-## Production Deployment (Ubuntu + Nginx + Gunicorn + systemd)
+## Production Deployment
 
 ```bash
-# Schema migrations (all subsequent deployments)
 flask db upgrade
-
-# Reload app
 sudo systemctl reload passkeeper
 ```
 
-For full initial setup instructions (Nginx config, systemd unit, Certbot, etc.) refer to the original deployment guide in this file's history or `scripts/passkeeper-nginx.conf` / `scripts/passkeeper.service`.
-
----
-
-## Python Dependencies (`requirements.txt`)
+## Python Dependencies
 
 ```
-flask>=3.0
-flask-sqlalchemy>=3.1
-flask-migrate>=4.0
-flask-login>=0.6
-flask-wtf>=1.2
-flask-limiter>=3.5
-flask-cors>=4.0
-pymysql>=1.1
-argon2-cffi>=23.1
-pyjwt>=2.8
-python-dotenv>=1.0
-gunicorn>=21.0
-pyotp>=2.9.0
-qrcode[pil]>=7.4.2
-cryptography>=42.0    # AES-256-GCM server-side TOTP secret encryption
-redis>=5.0            # Shared rate-limit storage across Gunicorn workers
+flask>=3.0  flask-sqlalchemy>=3.1  flask-migrate>=4.0  flask-login>=0.6
+flask-wtf>=1.2  flask-limiter>=3.5  flask-cors>=4.0
+pymysql>=1.1  argon2-cffi>=23.1  pyjwt>=2.8  python-dotenv>=1.0
+gunicorn>=21.0  pyotp>=2.9.0  qrcode[pil]>=7.4.2
+cryptography>=42.0   # TOTP secret encryption
+redis>=5.0           # Rate-limit storage (required in production)
 ```
 
 ---
 
-## Migration History
-
-| Revision         | Description                                              |
-|------------------|----------------------------------------------------------|
-| `71d7158dd3b9`   | Add audit_logs table; fix sharing_public_key column type |
-| `a1b2c3d4e5f6`   | Encrypt TOTP secret at rest (totp_secret → VARCHAR(255), add totp_iv) |
-| `b2c3d4e5f6a7`   | Add account recovery columns (recovery_enc_salt, recovery_iv) |
-| `c3d4e5f6a7b8`   | Encrypt vault item name (add enc_name, iv_name to vault_items) |
-
----
-
 ## Notes
 
 - Never log decrypted vault data server-side
-- All encryption/decryption of vault data (including item names) happens in the browser
-- The server stores only encrypted blobs — zero-knowledge architecture
-- `enc_key_salt` is not secret on its own — only useful combined with the master password
-- **Redis is required in production** for rate limiting. Without it, each Gunicorn worker maintains its own counter.
-- **Recovery code is never stored server-side** — only the AES-256-GCM ciphertext of `enc_key_salt`
-- **Password change clears the recovery code** — user must regenerate from Account Settings
-- **The `#vault-list` element ID must not be renamed** — `vault.js` renders all vault items into it
-- **`save_blocklist`** in `chrome.storage.local` stores hostnames for which the save banner is suppressed
-- **`vault_items_cs` is in `chrome.storage.session`** — decrypted data never written to disk (changed from `local`)
-- **HIBP checks run progressively** — the security dashboard renders synchronous sections first, then fires parallel k-anonymity requests in the background
\ No newline at end of file
+- Tags live in `enc_data` as `plain.tags: string[]` — no schema change ever needed
+- `vault_items_cs` is in `chrome.storage.session` — decrypted data never written to disk
+- HIBP checks run progressively — synchronous sections render first, then parallel async checks
+- Clipboard cleared 30 s after every password/username copy (web app + extension)
+- Web-app idle timeout in `localStorage` (`web_idle_minutes`); default 15 min
+- Browser back/forward works for all five vault views via `history.pushState`
+- Pending save badge (`"!"`) set on `SAVE_CREDENTIALS`, cleared via `CLEAR_SAVE_BADGE`
+- Firefox: use `manifest.firefox.json` + `background.firefox.js` + `browser-polyfill.js`
+- Redis required in production for rate limiting
+- Recovery code never stored server-side; password change clears it (user must regenerate)
+- `save_blocklist` in `chrome.storage.local` suppresses save banner per hostname
\ No newline at end of file
diff --git a/README.md b/README.md
index 100f5f6..a334097 100644
--- a/README.md
+++ b/README.md
@@ -1,38 +1,50 @@
 # PassKeeper 🔐
 
-A self-hosted, zero-knowledge password manager — web app and browser extension. Modelled after LastPass, built on Flask + MySQL + Web Crypto API.
-
-Your master password and decrypted vault data **never leave your browser**. The server stores only encrypted blobs it cannot read.
+A self-hosted, zero-knowledge password manager — web app and Chrome/Firefox extension. Your master password and decrypted vault data **never leave your browser**.
 
 ---
 
 ## Features
 
 ### Web App
-- **Zero-knowledge encryption** — AES-256-GCM client-side, 600k-iteration PBKDF2 vault key derivation
-- **7 item types** — Passwords, Secure Notes, Payment Cards, Bank Accounts, Addresses, Identities, Passkeys
-- **TOTP/2FA support** — per-site TOTP codes stored inside the encrypted vault blob; live 6-digit display with countdown
-- **Folder organisation** — create, rename, delete folders; filter vault by folder
-- **Item sharing** — zero-knowledge ECDH P-256 re-encryption; share with any registered user
+- **Zero-knowledge encryption** — AES-256-GCM client-side; 600k-iteration PBKDF2 vault key
+- **7 item types** — Passwords, Secure Notes, Cards, Bank Accounts, Addresses, Identities, Passkeys
+- **Vault item tags** — comma-separated tags stored inside the encrypted blob; sidebar tag filter; live badge preview in modal; no schema change required
+- **Collapsible folder groups** — click any folder header in the vault list to collapse/expand; item count badge and chevron indicator; state persists across re-renders
+- **TOTP / 2FA** — per-site TOTP codes stored in `plain.totp_uri`; live 6-digit display with countdown
+- **Folder organisation** — create, rename, delete; filter vault by folder
+- **Item sharing** — ECDH P-256 zero-knowledge re-encryption; share with any registered user
 - **Emergency access** — configurable wait-timer access grant for a trusted contact
-- **Security dashboard** — weak, reused, and old password detection + **HaveIBeenPwned k-anonymity breach check** (passwords never transmitted)
-- **Account MFA** — TOTP-based login verification (Google Authenticator / Authy)
-- **Master password change** — atomic zero-knowledge re-encryption of the entire vault
+- **Security dashboard** — weak / reused / old / **no 2FA saved** / **HaveIBeenPwned breach check** (k-anonymity — passwords never transmitted)
+- **Import / Export** — encrypted JSON backup; CSV export (plaintext, handle carefully); import from Chrome, Bitwarden, and 1Password CSV formats
+- **Account MFA** — TOTP-based login (Google Authenticator / Authy)
+- **Master password change** — atomic zero-knowledge re-encryption of entire vault including item names
 - **Account recovery** — 128-bit recovery code; server never stores it
-- **Audit log** — server-side trail of all create/edit/delete actions; no sensitive data ever logged
-- **Encrypted item names** — item names stored as AES-256-GCM ciphertext; server holds only the item type as a label
-- **Responsive layout** — phone, tablet, laptop, and large desktop breakpoints; collapsible sidebar
+- **Audit log** — server-side trail of all create/edit/delete/import/export actions
+- **Encrypted item names** — `enc_name`/`iv_name`; server holds only the item type as a label
+- **Browser history** — back/forward button works for all views (`history.pushState`)
+- **Web-app auto-lock** — configurable inactivity timeout (5/10/15/30/60 min or Never); stored per browser in `localStorage`
+- **Clipboard auto-clear** — sensitive copies cleared after 30 seconds
+- **Responsive layout** — phone, tablet, laptop, large desktop; collapsible sidebar
 
-### Browser Extension (Chrome / Edge — Manifest V3)
-- **Autofill** — detects login forms; injects icon into username and password fields only (scored heuristic, not all text inputs)
-- **Suggestion dropdown** — anchored below the focused field; filters as you type; keyboard navigation (↑↓ Enter); fills with one click
-- **Smart domain matching** — matches vault items by domain name, handles bare domains (`github.com`) and subdomains
-- **Auto-save banner** — prompts to save or update credentials on form submit; duplicate detection; "Never for this site" blocklist
-- **Inline password generator** — length slider, charset toggles, strength indicator; fully CSPRNG (`crypto.getRandomValues` throughout)
-- **TOTP live display** — 6-digit code + countdown timer per item in the popup
-- **SSO bridge** — log in once on the web app; extension picks up the session automatically
-- **Idle lock** — configurable auto-lock timeout (1 / 5 / 10 / 30 min / Never)
-- **Security** — decrypted vault data stored in `chrome.storage.session` only (memory-only, never written to disk)
+### Browser Extension (Chrome / Edge — Manifest V3 + Firefox — Manifest V2)
+- **Autofill** — detects login forms; injects icon into username and password fields only (scored heuristic, not all inputs)
+- **Smart domain matching** — matches by domain name; handles bare domains (`github.com`) and subdomains
+- **Suggestion dropdown** — filters as you type; keyboard navigation (↑↓ Enter); one-click fill
+- **Collapsible folder groups** — "All items" tab groups by folder with collapse/expand toggle matching the web app UX
+- **Favorites tab** — items tagged `favorite` in the web app appear in a dedicated tab; marked with ★
+- **Tag display** — purple badge pills on item rows; tags sourced from `plain.tags[]`
+- **Three-dot flyout menu** — contextual actions: Open URL / Copy username / Copy password; built dynamically from what the item has
+- **Dedicated copy-username button** — person icon alongside copy-password in every item row
+- **Auto-save banner** — save/update credentials on form submit; duplicate detection; "Never for this site" blocklist
+- **Pending-save badge** — red `!` on toolbar icon when a credential is waiting to be saved
+- **Inline password generator** — fully CSPRNG (`crypto.getRandomValues` throughout, `Math.random` never called)
+- **TOTP live display** — 6-digit code + countdown per item
+- **SSO bridge** — log in once on the web app; extension picks up the session
+- **Idle lock** — configurable auto-lock (1/5/10/30 min or Never)
+- **Clipboard auto-clear** — passwords/usernames cleared from clipboard after 30 seconds
+- **Keyboard shortcut** — `Ctrl+Shift+L` / `Cmd+Shift+L` to open popup (customisable at `chrome://extensions/shortcuts`)
+- **Firefox compatible** — separate MV2 manifest + background script; same popup/content/bridge code
 
 ---
 
@@ -42,18 +54,19 @@ Your master password and decrypted vault data **never leave your browser**. The
 Master Password
       │
       ├─ PBKDF2(email, 100k iter)  ──►  authHash  ──►  POST /api/auth/login
-      │                                                       │
-      │                                              Argon2id(authHash) stored in DB
+      │                                                  Argon2id(authHash) stored in DB
       │
-      └─ PBKDF2(enc_key_salt, 600k iter)  ──►  vaultKey (stays in browser memory only)
-                                                      │
-                                              AES-256-GCM encrypt
-                                                      │
-                                              enc_data + iv  ──►  POST /api/vault
-                                              enc_name + iv_name  (item name, encrypted separately)
+      └─ PBKDF2(enc_key_salt, 600k iter)  ──►  vaultKey (browser memory only)
+                                                    │
+                                            AES-256-GCM encrypt
+                                                    │
+                                      enc_data + iv     (item payload + tags)
+                                      enc_name + iv_name (item name)
+                                            │
+                                      POST /api/vault  ──►  Server stores ciphertext only
 ```
 
-The server is blind to all vault content. A database breach exposes only encrypted ciphertext.
+A database breach exposes only encrypted ciphertext. The server cannot read vault names, passwords, or tags.
 
 ---
 
@@ -66,7 +79,7 @@ The server is blind to all vault content. A database breach exposes only encrypt
 | Frontend | Vanilla JS, Web Crypto API, Jinja2 |
 | Auth | Argon2id + PBKDF2 + JWT (HS256) |
 | Encryption | AES-256-GCM (client-side) |
-| Extension | Chrome Manifest V3 |
+| Extension | Chrome MV3 / Firefox MV2 |
 | Web server | Nginx + Gunicorn + systemd |
 | Rate limiting | Flask-Limiter + Redis |
 | TLS | Let's Encrypt / Certbot |
@@ -76,136 +89,104 @@ The server is blind to all vault content. A database breach exposes only encrypt
 ## Getting Started
 
 ### Prerequisites
-
 - Python 3.12+
 - MySQL 8.x
-- Node.js is **not** required — no build step
+- No Node.js or build step required
 
 ### Development (Windows)
 
 ```bash
-# 1. Clone and set up virtual environment
 git clone https://github.com/yourname/passkeeper
 cd passkeeper
 python -m venv .venv
 .venv\Scripts\activate
 pip install -r requirements.txt
-
-# 2. Configure environment
 copy .env.example .env
 ```
 
 Edit `.env`:
-
 ```env
 FLASK_ENV=development
-SECRET_KEY=your-secret-key
-JWT_SECRET_KEY=your-jwt-secret
+SECRET_KEY=<64-char hex>
+JWT_SECRET_KEY=<64-char hex>
 MYSQL_HOST=localhost
 MYSQL_USER=passkeeper
 MYSQL_PASSWORD=yourpassword
 MYSQL_DB=passkeeper
-TOTP_ENCRYPTION_KEY=64-char-hex-string   # python -c "import secrets; print(secrets.token_hex(32))"
+TOTP_ENCRYPTION_KEY=<64-char hex>
 ```
 
 ```bash
-# 3. Create database
 mysql -u root -p -e "CREATE DATABASE passkeeper CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
-mysql -u root -p -e "CREATE USER 'passkeeper'@'localhost' IDENTIFIED BY 'yourpassword';"
-mysql -u root -p -e "GRANT ALL PRIVILEGES ON passkeeper.* TO 'passkeeper'@'localhost'; FLUSH PRIVILEGES;"
-
-# 4. Create tables
+mysql -u root -p -e "CREATE USER 'passkeeper'@'localhost' IDENTIFIED BY 'yourpassword'; GRANT ALL ON passkeeper.* TO 'passkeeper'@'localhost'; FLUSH PRIVILEGES;"
 python reset_db.py
-
-# 5. Run
 python run.py
 ```
 
-Open `http://localhost:5000`.
+Generate secrets:
+```bash
+python -c "import secrets; print(secrets.token_hex(32))"
+```
 
 ### Load the Extension (Chrome)
+1. `chrome://extensions/` → Enable **Developer mode**
+2. **Load unpacked** → select `extension/` folder
+3. Reload after any JS/CSS changes
 
-1. Open `chrome://extensions/`
-2. Enable **Developer mode** (top-right toggle)
-3. Click **Load unpacked** → select the `extension/` folder
-4. Reload the extension after any JS/CSS changes
-
-Content script logs appear in the **page's** DevTools console. Background service worker logs are at `chrome://extensions/` → PassKeeper → "Service Worker".
+### Load the Extension (Firefox)
+1. `about:debugging` → **This Firefox** → **Load Temporary Add-on**
+2. Select `extension/manifest.firefox.json`
 
 ---
 
 ## Production Deployment
 
 ### 1. Server dependencies
-
 ```bash
 sudo apt update && sudo apt install python3.12 python3.12-venv mysql-server nginx \
     certbot python3-certbot-nginx redis-server
 ```
 
 ### 2. Application setup
-
 ```bash
 cd /var/www/passkeeper
-python3.12 -m venv .venv
-source .venv/bin/activate
+python3.12 -m venv .venv && source .venv/bin/activate
 pip install -r requirements.txt
 cp .env.example .env   # set production values
 flask db upgrade       # run all migrations
 ```
 
 ### 3. systemd service
-
-Copy `scripts/passkeeper.service` to `/etc/systemd/system/passkeeper.service`, then:
-
 ```bash
-sudo systemctl daemon-reload
-sudo systemctl enable --now passkeeper
-journalctl -xeu passkeeper.service
+sudo cp scripts/passkeeper.service /etc/systemd/system/
+sudo systemctl daemon-reload && sudo systemctl enable --now passkeeper
 ```
 
-Key flags in the service unit: `--preload` (single app import, lower memory), `WatchdogSec=60s`, `Restart=on-failure`.
-
 ### 4. Nginx
-
-Copy `scripts/passkeeper-nginx.conf` to `/etc/nginx/sites-available/passkeeper`, update `server_name`, then:
-
 ```bash
+sudo cp scripts/passkeeper-nginx.conf /etc/nginx/sites-available/passkeeper
 sudo ln -s /etc/nginx/sites-available/passkeeper /etc/nginx/sites-enabled/
 sudo certbot --nginx -d yourdomain.com
 sudo nginx -t && sudo systemctl reload nginx
 ```
 
-The Nginx config uses an `upstream` block with `proxy_next_upstream` for zero-downtime Gunicorn restarts, dual rate-limit zones (auth endpoints and general API), and `Cache-Control: immutable` for static assets.
-
-### 5. Schema migrations (future updates)
-
+### 5. Future schema migrations
 ```bash
-flask db upgrade
-sudo systemctl reload passkeeper
+flask db upgrade && sudo systemctl reload passkeeper
 ```
 
 ---
 
 ## Environment Variables
 
-| Variable | Description | Example |
-|---|---|---|
-| `SECRET_KEY` | Flask session secret | 64-char random hex |
-| `JWT_SECRET_KEY` | JWT signing secret | 64-char random hex |
-| `MYSQL_HOST` | MySQL host | `localhost` |
-| `MYSQL_USER` | MySQL username | `passkeeper` |
-| `MYSQL_PASSWORD` | MySQL password | — |
-| `MYSQL_DB` | Database name | `passkeeper` |
-| `TOTP_ENCRYPTION_KEY` | Server-side AES key for TOTP secrets | 64-char hex |
-| `RATELIMIT_STORAGE_URI` | Redis URI for rate limiting | `redis://127.0.0.1:6379/0` |
-| `CORS_ORIGINS` | Allowed CORS origins | `https://yourdomain.com` |
-
-Generate secrets:
-
-```bash
-python -c "import secrets; print(secrets.token_hex(32))"
-```
+| Variable | Description |
+|---|---|
+| `SECRET_KEY` | Flask session secret (64-char hex) |
+| `JWT_SECRET_KEY` | JWT signing secret (64-char hex) |
+| `MYSQL_HOST` / `MYSQL_USER` / `MYSQL_PASSWORD` / `MYSQL_DB` | Database |
+| `TOTP_ENCRYPTION_KEY` | Server-side AES key for TOTP secrets (64-char hex) |
+| `RATELIMIT_STORAGE_URI` | Redis URI — required in production (`redis://127.0.0.1:6379/0`) |
+| `CORS_ORIGINS` | Allowed origins (`*` in dev, domain in prod) |
 
 ---
 
@@ -213,64 +194,71 @@ python -c "import secrets; print(secrets.token_hex(32))"
 
 ```
 passkeeper/
-├── app/                    # Flask application
-│   ├── models/             # SQLAlchemy models
-│   ├── routes/             # API blueprints (auth, vault, folders, sharing, emergency)
-│   ├── services/           # Auth service (Argon2id, JWT, TOTP encryption)
-│   ├── static/js/          # Client-side crypto + vault UI
-│   └── templates/          # Jinja2 HTML templates
-├── extension/              # Chrome extension (Manifest V3)
-│   ├── popup/              # Popup UI (HTML + CSS + JS)
-│   ├── content/            # Content script (form detection, autofill icon, dropdown)
-│   ├── shared/             # Shared crypto (vault key, encryptName/decryptName)
-│   ├── bridge/             # SSO bridge (web app ↔ extension session sync)
-│   └── background.js       # Service worker (badges, message relay, idle lock)
-├── migrations/             # Alembic migration scripts
-├── scripts/                # Nginx config, systemd unit, backup scripts
-├── reset_db.py             # Dev-only: drop + recreate all tables
-├── requirements.txt
-├── run.py                  # Development server entry point
-└── wsgi.py                 # Gunicorn entry point
+├── app/                  # Flask application
+│   ├── models/           # SQLAlchemy models
+│   ├── routes/           # API blueprints (auth, vault, folders, sharing, emergency)
+│   ├── services/         # Auth (Argon2id, JWT, TOTP encryption)
+│   ├── static/js/        # Client-side crypto + vault UI
+│   └── templates/        # Jinja2 templates
+├── extension/            # Browser extension
+│   ├── popup/            # Popup UI
+│   ├── content/          # Content script (autofill, field detection)
+│   ├── shared/           # Shared crypto + Firefox polyfill
+│   ├── bridge/           # SSO bridge
+│   ├── background.js     # Chrome MV3 service worker
+│   ├── background.firefox.js  # Firefox MV2 background page
+│   ├── manifest.json          # Chrome/Edge MV3
+│   └── manifest.firefox.json  # Firefox MV2
+├── migrations/           # Alembic migration scripts
+├── scripts/              # Nginx, systemd, backup
+└── requirements.txt
 ```
 
 ---
 
 ## API Overview
 
-All vault and folder endpoints require `Authorization: Bearer <access_token>`.
+All vault/folder endpoints require `Authorization: Bearer <access_token>`.
 
 | Method | Endpoint | Description |
 |---|---|---|
 | POST | `/api/auth/register` | Create account |
-| POST | `/api/auth/login` | Authenticate; returns tokens or MFA challenge |
-| POST | `/api/auth/mfa/verify` | Complete MFA step |
-| POST | `/api/auth/refresh` | Rotate refresh token |
-| POST | `/api/auth/logout` | Blacklist both tokens |
-| GET | `/api/vault` | List all encrypted vault items |
-| POST | `/api/vault` | Create item (`enc_data`, `iv`, `enc_name`, `iv_name`) |
+| POST | `/api/auth/login` | Authenticate |
+| POST | `/api/auth/mfa/verify` | Complete MFA |
+| POST | `/api/auth/refresh` | Rotate tokens |
+| POST | `/api/auth/logout` | Blacklist tokens |
+| GET | `/api/vault` | List encrypted items |
+| POST | `/api/vault` | Create item (`enc_data`, `iv`, `enc_name`, `iv_name`, tags in payload) |
 | PUT | `/api/vault/<id>` | Update item |
 | DELETE | `/api/vault/<id>` | Delete item |
-| GET | `/api/folders` | List folders |
+| GET | `/api/vault/export` | Download encrypted JSON backup |
+| POST | `/api/vault/import` | Bulk import; returns `{ imported, skipped }` |
+| GET/POST | `/api/folders` | List / create folders |
 | POST | `/api/sharing` | Share item (ECDH re-encryption) |
 | POST | `/api/emergency` | Create emergency access grant |
-| POST | `/api/auth/change-password` | Atomic vault re-encryption on password change |
-| POST | `/api/auth/recover` | Account recovery (one-time use) |
+| POST | `/api/auth/change-password` | Atomic vault re-encryption |
+| POST | `/api/auth/recover` | Account recovery (one-time) |
+
+---
+
+## Item Tagging
+
+Tags are stored as `plain.tags: string[]` inside the encrypted vault blob — the server never sees them and no schema change is required.
+
+**Web app:** Add tags in the item edit modal (comma-separated). Tags appear as purple badge pills on item rows. A Tags section in the sidebar lets you filter by any tag.
+
+**Extension:** Tags appear as `.pk-tag` badges on item rows. Items tagged `favorite` appear in the **Favorites** tab and show a ★ in the site label.
 
 ---
 
 ## Backup
 
-Automated MySQL backups with 30-day retention:
-
 ```bash
 # Install cron job
 sudo cp scripts/passkeeper-logrotate /etc/logrotate.d/passkeeper
 crontab scripts/backup.cron
-```
 
-Manual backup:
-
-```bash
+# Manual backup
 bash scripts/backup_db.sh
 ```