From 569777ce8a586f2c90881ff4c3d3e5ac8f09a949 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Zo=C3=AB?= <zoe@guido-it.nl>
Date: Wed, 26 Aug 2026 15:45:58 +0200
Subject: [PATCH] docs: update README with current feature set and
 prerequisites

---
 AGENTS.md | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md |  8 ++++----
 2 files changed, 55 insertions(+), 4 deletions(-)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5e68bfa
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,51 @@
+# AGENTS.md — decky-vaultwarden
+
+## What this is
+
+Decky Loader plugin for Steam Deck. Provides a Bitwarden/Vaultwarden password manager client in the Decky quick access panel.
+
+**Two-language architecture:**
+- **Python backend** (`main.py`, `bitwarden_client.py`, `crypto.py`, `clipboard.py`, `totp.py`) — crypto, API calls, vault decryption. Loaded by Decky Loader.
+- **TypeScript/React frontend** (`src/`) — UI rendered in Decky panel. Calls Python backend via Decky's `call()` API.
+
+## Build commands
+
+| Command | What it does |
+|---------|-------------|
+| `npm run build` | Rollup compiles TS to `dist/`, then packages everything (dist + Python files + `py_modules/` + plugin.json) into `out/Vaultwarden.zip` |
+| `npm run watch` | Rollup watch mode (frontend only) |
+| `npm run typecheck` | `tsc --noEmit` — type checking, no emit |
+| `npm run bundle-deps` | Downloads Python wheels into `py_modules/` (see below) |
+
+**No test, lint, or formatter commands exist.** No CI workflows.
+
+## Python dependency bundling
+
+`py_modules/` contains pre-compiled manylinux wheels (x86_64) for Python 3.11. These are checked into git.
+
+To regenerate: `npm run bundle-deps` (runs `scripts/bundle-deps.sh`). Downloads wheels from PyPI and extracts them into `py_modules/`.
+
+The bundled packages include: aiohttp, cryptography, argon2, pyotp, cffi, and transitive deps.
+
+## Key entrypoints
+
+- **Plugin entry (Python):** `main.py` — `Plugin` class. All methods here are callable from frontend via `call()`.
+- **Plugin entry (TS):** `src/index.tsx` — `definePlugin()`. Renders `VaultwardenPlugin` component.
+- **API bridge:** `src/api/backend.ts` — `VaultApi` class wraps all `call()` invocations to Python.
+- **State management:** `src/hooks/useVault.ts` — manages vault state machine (logged_out → loading → unlocked, etc).
+
+## Build output
+
+`out/Vaultwarden.zip` is the installable Decky plugin. Created by `npm run build`. Contains:
+- `dist/` (compiled frontend JS)
+- All Python files
+- `py_modules/` (bundled deps)
+- `plugin.json`, `defaults/settings.json`
+
+## Gotchas
+
+- **No `node_modules` rebuild needed for Python changes.** The Python files are copied as-is into the zip.
+- **`py_modules/` is checked into git** with pre-compiled wheels. If you modify Python deps in `requirements.txt`, re-run `npm run bundle-deps` and commit the updated `py_modules/`.
+- **Clipboard has two paths:** Python `clipboard.py` (xclip/xsel with auto-clear) and frontend `navigator.clipboard`. They serve different purposes — don't confuse them.
+- **Target platform:** x86_64 Linux (Steam Deck). Python wheels are platform-specific.
+- **`src/utils/`** exists but is empty.
diff --git a/README.md b/README.md
index 324a920..4999a1d 100644
--- a/README.md
+++ b/README.md
@@ -7,10 +7,11 @@ A Decky Loader plugin for accessing Bitwarden and Vaultwarden passwords directly
 - **Login with Email + Password** or **API Key** (supports self-hosted Vaultwarden)
 - **Browse vault** organized by folders with search
 - **Copy passwords, usernames, and TOTP codes** to clipboard (auto-clears after 60 seconds)
+- **Supports multiple item types** - Logins, Secure Notes, Credit Cards, and Identities
+- **View custom fields and notes** for each vault item
 - **PIN unlock** - set up a PIN to avoid entering your master password every time
 - **2FA support** - handles two-factor authentication during login
-- **Offline capable** - once synced, vault data is cached locally
-- **Auto-lock** - vault locks when Steam Deck goes to sleep
+- **Auto-lock** - vault locks when Steam Deck goes to sleep (configurable)
 
 ## Installation
 
@@ -59,9 +60,8 @@ For automation or if you prefer API keys:
 
 ### Prerequisites
 
-- Node.js v16.14+ and pnpm v9
+- Node.js v16.14+ and npm
 - Python 3.10+ with pip
-- Docker (for backend builds)
 
 ### Build