diff --git a/docs/superpowers/specs/2026-03-18-vaultwarden-design.md b/docs/superpowers/specs/2026-03-18-vaultwarden-design.md
new file mode 100644
index 0000000..6c4a1a7
--- /dev/null
+++ b/docs/superpowers/specs/2026-03-18-vaultwarden-design.md
@@ -0,0 +1,88 @@
+# Vaultwarden Module Design
+
+## Overview
+
+Add Vaultwarden (a lightweight Bitwarden-compatible password manager) as a NixOS module following the existing Podman container pattern.
+
+## Requirements
+
+- Domain: `vault.ashisgreat.xyz`
+- WebSocket support for real-time sync
+- Admin panel enabled
+- No email functionality needed
+
+## Module Options
+
+```nix
+myModules.vaultwarden = {
+  enable = lib.mkEnableOption "Vaultwarden password manager";
+
+  domain = lib.mkOption {
+    type = lib.types.str;
+    example = "vault.example.com";
+    description = "Public domain for Vaultwarden";
+  };
+
+  port = lib.mkOption {
+    type = lib.types.port;
+    default = 8222;
+    description = "HTTP port for Vaultwarden web interface";
+  };
+
+  websocketPort = lib.mkOption {
+    type = lib.types.port;
+    default = 3012;
+    description = "WebSocket port for real-time sync";
+  };
+};
+```
+
+## Architecture
+
+### Container Configuration
+
+- **Image**: `vaultwarden/server:latest`
+- **Ports**:
+  - HTTP: `127.0.0.1:8222 → 80`
+  - WebSocket: `127.0.0.1:3012 → 3012`
+- **Volumes**:
+  - `vaultwarden-data:/data` - Persistent storage for SQLite database
+- **Environment**:
+  - `ADMIN_TOKEN` - From SOPS secret
+  - `SHOW_PASSWORD_HINT=false` - Disabled since no email
+  - `SIGNUPS_ALLOWED=true` - Can be changed via admin panel
+
+### Nginx Integration
+
+The module adds the domain to `myModules.nginx.domains` with:
+- Main location `/` → proxy to HTTP port
+- WebSocket location `/notifications/hub` → proxy to WebSocket port with upgrade headers
+
+### Secrets
+
+One secret required in `secrets/secrets.yaml`:
+- `vaultwarden_admin_token` - Token for accessing the admin panel at `/admin`
+
+SOPS template `vaultwarden.env` will inject the admin token.
+
+## Files to Create/Modify
+
+| File | Action |
+|------|--------|
+| `modules/vaultwarden.nix` | Create - new module |
+| `modules/default.nix` | Modify - add import |
+| `configuration.nix` | Modify - enable module and add secrets |
+| `secrets/secrets.yaml` | Modify - add admin token (manual) |
+
+## Usage
+
+After deployment:
+1. Navigate to `https://vault.ashisgreat.xyz`
+2. Create an account
+3. Access admin panel at `https://vault.ashisgreat.xyz/admin` with the admin token
+
+## Dependencies
+
+- `myModules.podman` - Container runtime
+- `myModules.nginx` - Reverse proxy (for domain registration)
+- SOPS-nix - Secrets management