diff --git a/CLAUDE.md b/CLAUDE.md
index 384b62f..7aa1953 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -745,4 +745,101 @@ browser extension — not from PassKeeper. These can be ignored.
 The `[PassKeeper] decorateFields: host=…, matched=0 of 0 items` log from
 `content.js` is a routine debug message (not an error): the content script found
 no stored credentials matching the current hostname, which is expected on the vault
-page itself.
\ No newline at end of file
+page itself.
+
+---
+
+## Roadmap / To-Do
+
+Features planned for future implementation. Ordered by priority within each category.
+
+### High priority — user-facing
+
+**1. One-time share links**
+Generate a time-limited, single-use encrypted link to share a credential with someone who has no PassKeeper account. The decryption key lives in the URL fragment (never sent to server). Auto-expires and self-destructs after first view.
+- New DB table: `share_links` (token, enc_data, iv, enc_key_fragment_hash, expires_at, used_at)
+- Public route: `GET /s/<token>` — serves a minimal HTML page
+- Client derives key from URL fragment, decrypts, displays once
+- No auth required for recipient
+
+**2. Custom fields**
+Let users add arbitrary key-value pairs to any item type. Fields stored encrypted inside `plain.custom_fields: [{label, value}]` — no schema change needed.
+- Add "Add field" button in item modal
+- Renders as label + value rows; value masked by default for sensitive fields
+- Searchable via expanded `handleSearch`
+
+**3. Trusted devices**
+After successful login + MFA, mark the browser as trusted for N days — MFA skipped on subsequent logins from that device.
+- Store a signed `trusted_device` cookie (HMAC of device fingerprint + user_id + expiry)
+- Server verifies on login; if valid, skip MFA challenge
+- User can revoke trusted devices in Account Settings
+
+### Medium priority — security / UX
+
+**4. Email notifications**
+Send email on security events: new login from unknown IP, MFA disabled, master password changed, emergency access requested.
+- Requires SMTP config in `.env` (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASSWORD`, `SMTP_FROM`)
+- Use Flask-Mail or smtplib directly
+- User can opt out per event type in Account Settings
+
+**5. Audit log improvements**
+Current audit log is a raw list. Add:
+- Filter by action type and date range
+- Export to CSV
+- Pagination (currently loads all at once)
+
+**6. Access from unknown IP alert**
+On login, compare client IP against last-seen IPs for the user. If new, flag in the audit log and (if email configured) send a notification.
+
+### Lower priority — platform
+
+**7. Vault item attachments**
+Encrypt files client-side (AES-256-GCM), store as base64 blobs attached to vault items.
+- New DB table: `vault_attachments` (item_id, enc_data, iv, filename_enc, iv_filename, size, created_at)
+- Client-side size limit (e.g. 5 MB per file, 25 MB per vault)
+- Download: decrypt in browser, trigger download via Blob URL
+
+**8. Collections / nested folders**
+Group folders into top-level collections (e.g. "Work", "Personal").
+- New DB table: `collections` (user_id, name)
+- `folders.collection_id` FK
+- Sidebar renders collection → folder → items hierarchy
+
+**9. iOS AutoFill Extension**
+Expose PassKeeper as an iOS Credential Provider so it fills in Safari and other apps natively.
+- Requires iOS Credential Provider Extension target in Xcode
+- Shares encrypted vault data with the extension via App Groups
+- Ties into the existing JQC iOS project infrastructure
+
+**10. Extension — TOTP QR capture**
+Detect 2FA setup QR codes on screen during account registration flows.
+- Content script watches for `<img>` or `<canvas>` elements containing `otpauth://` URIs
+- Prompts user to save the TOTP secret to the matching vault item
+
+**11. Admin panel** (multi-user deployments)
+- User management (invite, disable, delete)
+- Per-user storage and audit log review
+- Requires role column on `users` table
+
+### Infrastructure
+
+**12. Backup verification cron**
+Extend `backup.cron` to run a weekly restore test into a throwaway DB, verifying backup integrity automatically.
+
+**13. Health check endpoint**
+`GET /health` — returns `{"status": "ok", "db": "ok", "version": "x.y.z"}`. Used by uptime monitors (UptimeRobot, etc.).
+
+---
+
+## CI Pipeline
+
+`.gitea/workflows/ci.yml` runs on every push to `main`, `master`, `dev`.
+
+**Jobs:**
+1. `lint-python` — flake8 (F821 and real errors; style noise suppressed)
+2. `syntax-check` — `ast.parse` all `app/` Python files
+3. `migration-check` — single Alembic head, no duplicate revision IDs
+4. `js-syntax` — `node -e "new Function(...)"` on all vault/extension JS files
+5. `build-extension` — produces `passkeeper-extension-chrome.zip` and `passkeeper-extension-firefox.zip` as artifacts (30-day retention)
+
+**Runner:** self-hosted host-mode runner on the production server. Requires `python3`, `pip3`, `node`, `zip` on the host. No Docker needed.
\ No newline at end of file
diff --git a/README.md b/README.md
index 7129938..a1af6b3 100644
--- a/README.md
+++ b/README.md
@@ -291,4 +291,23 @@ bash scripts/backup_db.sh
 
 ## Licence
 
-MIT — see `LICENSE`.
\ No newline at end of file
+MIT — see `LICENSE`.
+
+---
+
+## Roadmap
+
+| # | Feature | Notes |
+|---|---------|-------|
+| 1 | **One-time share links** | Single-use encrypted link for non-account recipients; key in URL fragment |
+| 2 | **Custom fields** | Arbitrary key-value pairs per item; stored in encrypted blob |
+| 3 | **Trusted devices** | Skip MFA for N days on trusted browsers |
+| 4 | **Email notifications** | Alert on login from new IP, MFA changes, password change |
+| 5 | **Audit log improvements** | Filter by type/date, CSV export, pagination |
+| 6 | **Vault item attachments** | Client-side encrypted file attachments per item |
+| 7 | **Collections / nested folders** | Group folders into top-level collections |
+| 8 | **iOS AutoFill Extension** | Native credential filling in Safari and iOS apps |
+| 9 | **Extension TOTP QR capture** | Detect and save TOTP secrets during 2FA setup |
+| 10 | **Admin panel** | User management for multi-user deployments |
+| 11 | **Backup verification cron** | Weekly automated restore test |
+| 12 | **Health check endpoint** | `GET /health` for uptime monitors |
\ No newline at end of file