docs(user): org item-type parity shipped — flip concepts + faq org sections

All four v0.8.1 streams merged (main 4c0a289): org add now supports all 7 item
types (card/key/totp/document) and org edit is interactive. Flip the two
high-level org sections from "coming" to shipped, grounded in the real merged
`relicario org add <type> --collection …` surface; remove the rebase TODO markers.

user_docs/README.md

@@ -0,0 +1,51 @@
+# Relicario — User Guide
+
+Welcome! Relicario is a password manager that keeps your logins, cards, notes, and files
+safe — and keeps **you** in control of where they live. This guide is for everyday users:
+no programming or cryptography knowledge required.
+
+> **The one-minute version.** Your vault lives in a git repository *you* control (your own
+> Gitea or GitHub). The server only ever sees scrambled, unreadable data. To unlock your
+> vault you need **two things together**: a **passphrase** you remember, and a **reference
+> photo** (an ordinary JPEG you chose, with a secret hidden inside it). Neither one alone can
+> open the vault — that's what keeps your secrets yours.
+
+## Start here
+
+New to Relicario? Read these first, in order:
+
+1. **[Getting started](getting-started.md)** — install it, create your first vault, and add your first login (about 10 minutes).
+2. **[How Relicario works](concepts.md)** — the two-factor idea, where your data is stored, and the one golden rule.
+3. **[Items](items.md)** — the seven kinds of things you can store, and how to add, view, edit, and delete them.
+
+## Everyday tasks
+
+- **[Passwords & generators](passwords-and-generators.md)** — create strong passwords and passphrases, and check how strong they are.
+- **[Two-factor codes (TOTP)](totp.md)** — store the rotating 6-digit codes for sites that use authenticator apps.
+- **[Attachments & documents](attachments-and-documents.md)** — keep files and scanned documents in your vault.
+- **[Organizing your vault](organizing.md)** — groups, tags, favorites, and search.
+- **[Sync & backup](sync-and-backup.md)** — use your vault on more than one computer, and back it up safely.
+- **[The browser extension](the-browser-extension.md)** — unlock, search, and autofill logins right in Chrome or Firefox.
+
+## Before you need it
+
+- **[Recovery — and its limits](recovery.md)** — how to protect against losing access, and the honest truth about what *cannot* be recovered. **Please read this one early, not after something goes wrong.**
+- **[FAQ](faq.md)** — quick answers to common questions.
+
+## For the technically curious
+
+This guide deliberately skips the engineering details. If you want to understand how the
+encryption, the hidden-image secret, or the data formats actually work, see the technical
+documentation in the repository:
+
+- [`../DESIGN.md`](../DESIGN.md) — the big picture across all the pieces.
+- [`../docs/CRYPTO.md`](../docs/CRYPTO.md) — how the two factors become a key, and how data is encrypted.
+- [`../docs/SECURITY.md`](../docs/SECURITY.md) — the threat model: what Relicario protects against, and what it doesn't.
+- [`../docs/FORMATS.md`](../docs/FORMATS.md) — the on-disk and wire formats.
+
+Relicario is free and open source under the GPL-3.0-or-later license — you're welcome to read,
+build, and verify every line.
+
+---
+
+**Next:** [Getting started](getting-started.md)

user_docs/attachments-and-documents.md

@@ -0,0 +1,154 @@
+# Files: documents & attachments
+
+This page covers two related ideas: storing a file as its own vault item (a **Document**), and attaching extra files to any existing item — like pinning a recovery-codes PDF to a login.
+
+---
+
+## Documents vs. attachments — what's the difference?
+
+| | What it is | How you create it |
+|---|---|---|
+| **Document item** | A file that *is* the item — a passport scan, a signed contract, a certificate. | `relicario add document` |
+| **Attachment** | A file pinned to an existing item — a recovery-codes PDF on a login, a photo on an identity. | `relicario attach` |
+
+Both are encrypted the same way. The git server only ever sees ciphertext — your file bytes never leave your device in plaintext.
+
+---
+
+## Storing a file as a Document item
+
+A Document item holds exactly one file, encrypted, as part of the vault.
+
+```
+relicario add document --file <FILE> --title "My Title"
+```
+
+`--file` is required. Any fields you leave out are prompted for interactively. You can also set `--group` and `--tags` (comma-separated):
+
+```
+relicario add document --file passport-scan.pdf --title "Passport scan" --group identity --tags travel,official
+```
+
+Once stored, use `relicario get <QUERY>` to look it up and `relicario extract` (see below) to pull the file back out.
+
+---
+
+## Attaching a file to any item
+
+You can pin one or more files to a login, secure note, identity, card, TOTP item, or Document. The item stays intact; the file is stored alongside it as an attachment.
+
+```
+relicario attach <QUERY> <FILE>
+```
+
+`<QUERY>` is the item's ID or a case-insensitive title substring. Example:
+
+```
+relicario attach "GitHub" recovery-codes.txt
+```
+
+---
+
+## Listing an item's attachments
+
+```
+relicario attachments <QUERY>
+```
+
+This prints the item's attachments with their **attachment IDs** (AIDs) — you need an AID to extract or remove a specific file.
+
+Example output (format may vary):
+
+```
+attachments on "GitHub login":
+  a3f8c1d2e5b6…  recovery-codes.txt  (4.2 KB)
+```
+
+---
+
+## Getting a file back out — `extract`
+
+```
+relicario extract <QUERY> <AID> [--out <PATH>]
+```
+
+- `<QUERY>` — item ID or title substring
+- `<AID>` — attachment ID from `relicario attachments`
+- `--out <PATH>` — where to write the file (defaults to the original filename in the current directory if omitted)
+
+Example:
+
+```
+relicario attachments "GitHub"
+# note the AID, e.g. a3f8c1d2e5b6…
+
+# Extract to a specific path:
+relicario extract "GitHub" a3f8c1d2e5b6 --out ~/Downloads/recovery-codes.txt
+
+# Or omit --out to write it under its original name in the current folder:
+relicario extract "GitHub" a3f8c1d2e5b6
+```
+
+---
+
+## Removing one attachment — `detach`
+
+`detach` removes a single attachment blob. The item itself stays in the vault.
+
+```
+relicario detach <QUERY> <AID>
+```
+
+Example:
+
+```
+relicario detach "GitHub" a3f8c1d2e5b6
+```
+
+This is different from `relicario purge <QUERY>`, which permanently deletes the **entire item** and all its attachments at once.
+
+---
+
+## Size limits
+
+Relicario enforces configurable size caps to keep your vault from ballooning. View the current limits:
+
+```
+relicario settings show
+```
+
+To change them:
+
+```
+relicario settings attachment-cap [OPTIONS]
+```
+
+Available options:
+
+| Flag | What it controls |
+|---|---|
+| `--per-attachment-max-bytes <N>` | Maximum size of a single attachment |
+| `--per-item-max-count <N>` | Maximum number of attachments on one item |
+| `--per-vault-soft-cap-bytes <N>` | Vault-wide soft cap (warning threshold) |
+| `--per-vault-hard-cap-bytes <N>` | Vault-wide hard cap (blocks new attachments) |
+
+Pass any combination of flags; omitted flags keep their current values.
+
+---
+
+## Quick reference
+
+| Goal | Command |
+|---|---|
+| Store a file as its own vault item | `relicario add document --file <FILE> --title …` |
+| Attach a file to an existing item | `relicario attach <QUERY> <FILE>` |
+| List an item's attachments (get AIDs) | `relicario attachments <QUERY>` |
+| Extract an attachment to disk | `relicario extract <QUERY> <AID> [--out <PATH>]` |
+| Remove one attachment (keep the item) | `relicario detach <QUERY> <AID>` |
+| Remove the whole item + all attachments | `relicario purge <QUERY>` |
+| View attachment size limits | `relicario settings show` |
+| Change attachment size limits | `relicario settings attachment-cap [OPTIONS]` |
+
+---
+
+**Next:** [Organizing your vault](organizing.md)

user_docs/concepts.md

@@ -0,0 +1,73 @@
+# How Relicario works
+
+This page explains the core ideas behind Relicario — no technical jargon required. Read this before anything else and the rest of the docs will make much more sense.
+
+---
+
+## Two factors, one key
+
+Relicario requires **two things** to unlock your vault:
+
+1. **Your passphrase** — something you remember and type. Think of it like the combination to a safe.
+2. **Your reference photo** — a JPEG image you chose when you set up your vault. Relicario hid a random secret inside the photo's pixels at setup time. You keep this file safe; it never gets uploaded to your git repository.
+
+Neither one alone does anything. They're like two keys that must turn at the same time — if either is missing, the vault stays shut.
+
+A helpful way to picture it: imagine a safety deposit box that needs both your key *and* the bank's key to open. Your passphrase is your key; your reference photo is the other. Lose either one, and you can't get in.
+
+> **For the curious:** Relicario derives the vault key using Argon2id (a memory-hard key derivation function) and encrypts everything with XChaCha20-Poly1305. See [../docs/CRYPTO.md](../docs/CRYPTO.md) for the full pipeline.
+
+---
+
+## Your data lives on your own git server
+
+Relicario stores your vault in a **git repository that you control** — hosted on your own Gitea instance or on GitHub. There is no Relicario-run cloud, no Relicario account, and no subscription.
+
+**The trust model in one sentence:** the server only ever stores ciphertext — your passphrase, your image secret, and your decrypted data never leave your device.
+
+Even if someone broke into your git server and downloaded every file, all they would have is encrypted noise. The keys to decrypt it never leave your machine.
+
+---
+
+## What's stored where
+
+When you initialize a vault, Relicario creates a few files inside your repository:
+
+| Path | What it is |
+|---|---|
+| `.relicario/` | Config directory: key-derivation salt and parameters (not secret) |
+| `manifest.enc` | Encrypted index — lets the app list item titles without decrypting everything |
+| `settings.enc` | Encrypted vault settings |
+| `items/<id>.enc` | One encrypted file per item |
+| `attachments/<item-id>/<att-id>.enc` | Encrypted attachment blobs |
+| `reference.jpg` | Your reference photo — **gitignored, never committed** |
+
+The last line is the important one: **your reference photo is deliberately excluded from git.** If you only back up your git remote, you have only backed up half of what you need. See [the golden rule](#the-golden-rule) below.
+
+Because your vault is a normal git repository, its full history is preserved automatically. Every change you make creates a new commit, giving you an audit trail you can browse with any standard git tool.
+
+---
+
+## Personal vault vs. org (team) vault
+
+Most people use a **personal vault** — one vault, one person, one set of two factors. That's what the rest of these docs cover.
+
+Relicario also supports a **multi-user org vault** for teams: an owner can add members, create collections (groups of items), and grant or revoke access per collection. Roles (owner, admin, member) control what each person can do, and every action is recorded in a signed audit log. The same trust model applies — the server only ever sees ciphertext, and access is enforced by collection grants, not by server-side permissions.
+
+An org vault stores the same seven item types as a personal vault — logins, secure notes, identities, cards, keys, documents, and TOTP codes — added with `relicario org add <type> --collection <name> …`. Members only ever see the collections they have been granted.
+
+For day-to-day use, see [Sync & backup](sync-and-backup.md) for syncing an org vault across devices.
+
+---
+
+## The golden rule
+
+> **Never forget your passphrase, and always keep at least one safe copy of your reference photo.**
+>
+> Losing your passphrase means your vault cannot be decrypted — there is no password reset and no backdoor. Losing your reference photo *and* your recovery QR (even if you still know your passphrase) has the same result. Losing both factors means your data is gone for good, by design.
+>
+> **What to do:** print or photograph your recovery QR and store it somewhere safe and offline. See [Recovery](recovery.md) for the full instructions.
+
+---
+
+**Next:** [Items](items.md)

user_docs/faq.md

@@ -0,0 +1,130 @@
+# Frequently Asked Questions
+
+Answers to common questions about how Relicario works, where your data lives, and what happens when things go wrong.
+
+---
+
+## What makes Relicario different? Why does it need two factors just to unlock my vault?
+
+Most password managers protect your vault with a single master password. Relicario requires **two factors** at the same time: your **passphrase** (something you remember) and a **reference photo** (a JPEG you chose during setup that carries a hidden 256-bit secret). Neither one can decrypt your vault on its own — both must be present together.
+
+The result: even if someone steals your passphrase, they cannot open your vault without also having your reference photo. Even if someone steals the reference photo file, they cannot open your vault without knowing your passphrase. For the technical details, see [../docs/CRYPTO.md](../docs/CRYPTO.md).
+
+---
+
+## Where is my data actually stored?
+
+Your vault is a **git repository that you control**. Relicario stores everything — encrypted items, an encrypted index, and settings — as files inside that repo, which you push to your own Gitea or GitHub server. Nothing goes to any server Relicario runs; there is no Relicario-operated cloud. The server only ever receives opaque ciphertext.
+
+---
+
+## Is my reference photo uploaded to the server?
+
+No. Your reference photo (the JPEG that carries the hidden image secret) is your second unlock factor. Relicario adds it to `.gitignore` at vault creation, so it is **never committed** and never pushed to your remote. If you only back up your git repository, you have **not** backed up your second factor.
+
+Keep at least one safe copy of `reference.jpg` somewhere separate — an encrypted external drive, a secure cloud folder of your own choice, or a printed [Recovery QR](recovery.md).
+
+---
+
+## What if I lose my passphrase or my reference photo?
+
+There is no password reset and no backdoor — by design. Here is the hard truth:
+
+- **Lose your passphrase** → your vault is unrecoverable (the recovery QR is also locked by your passphrase).
+- **Lose your reference photo AND your recovery QR** (even if you still know your passphrase) → the hidden image secret is gone → unrecoverable.
+- **Lose both factors** → your data is gone for good.
+
+See [Recovery](recovery.md) for how to generate a recovery QR while you still have everything, and where to keep it safe.
+
+---
+
+## Can I use Relicario on multiple computers?
+
+Yes. Because your vault is a git repo, you can sync it across machines with:
+
+```
+relicario sync
+```
+
+This does a `git pull --rebase` then `git push` against your configured remote. You will need to copy your `reference.jpg` to each computer you use (it is never in the repo, so you transfer it manually). You can also register each machine as a named device with `relicario device add`.
+
+---
+
+## Does Relicario work in my browser?
+
+Yes — there is a browser extension. It supports **Chrome/Chromium** (primary) and **Firefox (MV3)**. The extension lets you search your vault, reveal or copy fields, see live 30-second TOTP codes, and autofill login forms. The Chrome-only fullscreen vault tab supports all item types, add/edit/delete, settings, trash, devices, history, backup, and LastPass import.
+
+Install is currently build-from-source (no web-store listing). See [The browser extension](the-browser-extension.md) for step-by-step setup.
+
+---
+
+## Can my team share a vault?
+
+Relicario includes an org vault feature (`relicario org …`) with owner/admin/member roles, collections, per-collection access grants, and a signed audit log. It supports the full set of item types — logins, secure notes, identities, cards, keys, documents, and TOTP — added with `relicario org add <type> --collection <name> …`. The server only sees ciphertext; access is enforced by collection grants.
+
+**Current limitation:** the browser extension does **not** yet support org vaults — there is no org switch, browse, or write support in the extension. Org vault access is CLI-only for now.
+
+---
+
+## How do I generate a strong password?
+
+Use the built-in generator:
+
+```
+relicario generate
+```
+
+By default (outside a vault) it produces a 20-character random password with a safe symbol set. Inside an initialized vault it falls back to whatever you have set as your generator defaults. You can also generate a BIP39 word passphrase:
+
+```
+relicario generate --bip39
+```
+
+See [Passwords and generators](passwords-and-generators.md) for all options, including how to save your preferred defaults to the vault.
+
+---
+
+## How do I store 2FA codes (TOTP)?
+
+You can store TOTP secrets in two ways:
+
+1. **Standalone TOTP item** — stores just the authenticator code, separate from a login:
+   ```
+   relicario add totp --title "GitHub 2FA" --issuer "GitHub" --secret <BASE32>
+   ```
+2. **Attached to a login** — scan the site's QR code image and attach the TOTP secret directly to an existing login:
+   ```
+   relicario add login --title "GitHub" --username you@example.com --totp-qr qr.png
+   # or add it later:
+   relicario edit "GitHub" --totp-qr qr.png
+   ```
+
+The browser extension shows live 30-second codes inline for both login and standalone TOTP items. See [TOTP](totp.md) for more detail.
+
+---
+
+## How do I move off LastPass?
+
+Export your data from LastPass as a CSV (LastPass → Account Options → Export), then run:
+
+```
+relicario import lastpass /path/to/lastpass-export.csv
+```
+
+Each row becomes a new item in your vault. Rows that fail to parse are skipped and reported on stderr. Title collisions are kept as-is (no automatic deduplication).
+
+---
+
+## Is there a mobile app?
+
+Not yet. There are no Relicario mobile apps at this time.
+
+---
+
+## Is Relicario free / open source?
+
+Yes. Relicario is free and open source, released under the **GNU General Public License v3.0 or later** (GPL-3.0-or-later). You can read, build, run, and modify it yourself — which is also what lets you verify that your secrets never leave your device. See the `LICENSE` file in the repository for the full terms.
+
+---
+
+**Next:** [Back to the guide index](README.md)

user_docs/getting-started.md

@@ -0,0 +1,177 @@
+# Getting started with Relicario
+
+This page walks you through building Relicario from source, creating your first vault, and adding your first login — from zero to password manager in about ten minutes.
+
+---
+
+## 1. Build and install the CLI
+
+Relicario is currently distributed as source code, so you will need the Rust toolchain (`cargo`) installed. If you do not have it yet, visit [rustup.rs](https://rustup.rs) and follow the instructions there.
+
+Clone the Relicario repository, then build the CLI:
+
+```bash
+# Fast debug build (good for trying things out)
+cargo build -p relicario-cli
+
+# Optimized release build (recommended for everyday use)
+cargo build --release -p relicario-cli
+```
+
+The debug binary ends up at `target/debug/relicario`. The release binary ends up at `target/release/relicario`. You can copy either one to somewhere on your `$PATH`, for example:
+
+```bash
+cp target/release/relicario ~/.local/bin/relicario
+```
+
+Or run it in place using `cargo run`:
+
+```bash
+cargo run -p relicario-cli -- --help
+```
+
+---
+
+## 2. Create your first vault
+
+A Relicario vault is a regular git repository, and `relicario init` sets that up for you. Create an empty directory, move into it, and initialize the vault inside.
+
+```bash
+mkdir ~/my-vault
+cd ~/my-vault
+relicario init --image /path/to/your-photo.jpg
+```
+
+Replace `/path/to/your-photo.jpg` with any JPEG you own — a snapshot from your phone, a landscape photo, anything works.
+
+### What happens during `init`
+
+1. Relicario asks you to **choose a passphrase**, then to type it again to confirm. Pick something memorable but not trivial — Relicario rejects very weak passphrases. Your typing is not echoed to the terminal.
+2. It generates a random 256-bit secret and hides it inside the pixels of your photo, writing a new file called `reference.jpg` (in the vault directory by default).
+3. It sets up the git repository, creates the encrypted vault files, adds a `.gitignore`, and makes the first commit.
+4. It prints something like:
+
+   ```
+   Vault initialized at /home/you/my-vault
+   Reference image: reference.jpg
+     → back this file up somewhere safe; it is your second factor.
+   ```
+
+### The two factors — and why the reference image matters
+
+Relicario uses **two factors** to unlock your vault:
+
+- **Factor 1 — your passphrase:** something you memorize and type at the terminal.
+- **Factor 2 — your reference image:** the `reference.jpg` file produced during `init`. It carries the hidden secret that, combined with your passphrase, derives the decryption key. Neither factor alone can unlock anything.
+
+**Critical:** `reference.jpg` is intentionally **not** committed to your git repository (it is listed in `.gitignore`). This means if you push your vault to a git remote, the second factor does NOT go with it — which is exactly the point.
+
+> **Back this file up separately.** Copy `reference.jpg` to a USB drive, encrypted cloud storage, or a printed recovery QR (see [Recovery](recovery.md)). If you lose your reference image AND your recovery QR, your vault data is gone for good — there is no backdoor.
+
+For the technically curious, the cryptographic details are in [../docs/CRYPTO.md](../docs/CRYPTO.md) and the threat model is in [../docs/SECURITY.md](../docs/SECURITY.md).
+
+---
+
+## 3. Your first unlock
+
+Every Relicario command that reads or writes vault data unlocks the vault first, then drops the key when it exits. There is no persistent "unlocked session" in the CLI.
+
+Run commands from **inside your vault directory** (the one containing `.relicario/`) or any subdirectory of it — Relicario walks up to find the vault, just like git does.
+
+When you run a vault command, Relicario:
+
+1. Looks for your reference image via the `RELICARIO_IMAGE` environment variable; if not set, checks for `reference.jpg` in the vault directory; if neither is found, prompts `Reference image path:`.
+2. Prompts `Passphrase:` (input is hidden).
+
+If both are correct, the vault opens. If either is wrong or the image has been modified, the command fails.
+
+### Set `RELICARIO_IMAGE` to avoid the prompt
+
+If `reference.jpg` is not in the vault directory (for example, you keep it on a separate USB drive), set the environment variable so you are not prompted every time:
+
+```bash
+export RELICARIO_IMAGE=/media/usb/my-vault-reference.jpg
+```
+
+Add that line to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) to make it permanent. If `reference.jpg` lives right in the vault directory, Relicario finds it automatically and you do not need to set this variable.
+
+---
+
+## 4. Add your first login
+
+```bash
+relicario add login \
+  --title "GitHub" \
+  --username "yourname@example.com" \
+  --url "https://github.com" \
+  --password-prompt
+```
+
+- `--title` is the name you will use to find the item later.
+- `--username` and `--url` are stored in plaintext (visible in listings).
+- `--password-prompt` asks for your password at a hidden prompt. Alternatively, pass `--password <PASSWORD>` inline or `--password-stdin` to pipe it in from a script.
+
+Any flag you leave out is asked interactively, so you can also just run:
+
+```bash
+relicario add login
+```
+
+...and answer the prompts one at a time.
+
+After entering your vault passphrase, the item is encrypted and committed to git.
+
+---
+
+## 5. View and list your items
+
+### View a specific item
+
+```bash
+relicario get GitHub
+```
+
+Pass an item's title (or any case-insensitive substring of it) as the query. Secrets like the password are **masked** by default — they show as `********`.
+
+To reveal the actual values:
+
+```bash
+relicario get GitHub --show
+```
+
+To copy the primary secret (the password for a login) to your clipboard:
+
+```bash
+relicario get GitHub --copy
+```
+
+The clipboard is automatically cleared after **30 seconds**.
+
+### List all items
+
+```bash
+relicario list
+```
+
+Filter by type, group, or tag:
+
+```bash
+relicario list --type login
+relicario list --group Work
+relicario list --tag important
+```
+
+---
+
+## 6. What to do next
+
+You now have a working vault with your first login. A few things worth doing right away:
+
+- **Back up your reference image.** Copy `reference.jpg` somewhere safe before you add more data to the vault. See [Recovery](recovery.md) for the recovery QR option.
+- **Push your vault to a remote.** Add a Gitea or GitHub remote and run `relicario sync` to push. Your ciphertext is safe to store on a server — the server never sees your passphrase or your reference image.
+- **Learn about the item types.** Relicario can store logins, secure notes, identities, payment cards, API/SSH keys, documents, and TOTP codes. See [Items](items.md).
+- **Try the browser extension.** Relicario has a Chrome/Chromium extension with autofill, live TOTP codes, and a full-featured vault tab. See [The browser extension](the-browser-extension.md).
+
+---
+
+**Next:** [Concepts](concepts.md)

user_docs/items.md

@@ -0,0 +1,317 @@
+# Items: the 7 types, and how to add, view, edit, and delete them
+
+This page covers every item type Relicario supports, the exact flags for creating each one, and all the commands for viewing, updating, and removing items.
+
+---
+
+## How items work
+
+Relicario stores secrets as *typed items* — each type has a fixed set of fields that match what you'd expect for that kind of secret (a login has a username and password; a card has a number and CVV; and so on).
+
+Secret fields — passwords, card numbers, TOTP secrets, key material — are entered at a **hidden prompt** by default so they never appear on screen. If you're scripting or piping input, use the corresponding `--*-stdin` flag to read the value from standard input instead.
+
+Every item type shares three optional organizational flags:
+
+| Flag | What it does |
+|------|--------------|
+| `--title <TITLE>` | Human-readable name shown in lists |
+| `--group <GROUP>` | A single folder-like label |
+| `--tags <TAGS>` | Comma-separated labels, e.g. `--tags work,banking` |
+
+Any field you don't pass on the command line is prompted for interactively — so you can run `relicario add login` with no flags at all and fill everything in at the prompts.
+
+---
+
+## The 7 item types
+
+### Login
+
+A username/password pair, optionally with a URL and a TOTP secret baked in.
+
+```
+relicario add login [OPTIONS]
+
+  --title <TITLE>
+  --username <USERNAME>
+  --url <URL>
+  --password <PASSWORD>      set password from the command line (visible in shell history)
+  --password-prompt          prompt for password (hidden input)
+  --password-stdin           read password from stdin (one line)
+  --favorite                 mark as a favorite
+  --totp-qr <PATH>           decode an otpauth:// QR image to fill the TOTP secret
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — create a login, prompting for the password:**
+
+```bash
+relicario add login --title "GitHub" --username octocat --url https://github.com --password-prompt
+```
+
+**Example — scripted, password from stdin:**
+
+```bash
+echo "hunter2" | relicario add login --title "GitHub" --username octocat --password-stdin
+```
+
+If you have a TOTP QR code saved as an image, `--totp-qr` decodes the `otpauth://` URI and links the TOTP secret to this login automatically. See [TOTP codes](totp.md) for more.
+
+---
+
+### Secure note
+
+A free-form text note. The body is entered interactively (type your note and press Ctrl-D to finish), or piped in via `--body-stdin`.
+
+```
+relicario add secure-note [OPTIONS]
+
+  --title <TITLE>
+  --body-stdin     read the note body from stdin (to EOF)
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — pipe a note body from a file:**
+
+```bash
+relicario add secure-note --title "Wi-Fi passwords" --body-stdin < notes.txt
+```
+
+---
+
+### Identity
+
+Personal details: full name, email, phone, and date of birth. None of these are secret fields — they're all prompted as plain text.
+
+```
+relicario add identity [OPTIONS]
+
+  --title <TITLE>
+  --full-name <FULL_NAME>
+  --email <EMAIL>
+  --phone <PHONE>
+  --date-of-birth <DATE_OF_BIRTH>
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example:**
+
+```bash
+relicario add identity --title "Personal" --full-name "Alex Rivera" --email alex@example.com
+```
+
+---
+
+### Card
+
+A payment card. The card number, CVV, and PIN are secrets — they're prompted (hidden input) unless you use the `--*-stdin` flags. The holder name and expiry are plain text.
+
+```
+relicario add card [OPTIONS]
+
+  --title <TITLE>
+  --holder <HOLDER>      cardholder name (plain text)
+  --expiry <EXPIRY>      expiry date (plain text)
+  --kind <KIND>          card type [default: credit]
+  --number-stdin         read card number from stdin (one line)
+  --cvv-stdin            read CVV from stdin (one line)
+  --pin-stdin            read PIN from stdin (one line)
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — create a credit card, entering number/CVV/PIN at hidden prompts:**
+
+```bash
+relicario add card --title "Chase Sapphire" --holder "Alex Rivera" --expiry "12/28"
+```
+
+Relicario will prompt you for the card number, CVV, and PIN in turn, with each hidden.
+
+---
+
+### Key
+
+A cryptographic key or any block of key material (SSH private key, API key, certificate, etc.). The material itself is a multiline secret entered interactively (Ctrl-D to finish) or via `--material-stdin`.
+
+```
+relicario add key [OPTIONS]
+
+  --title <TITLE>
+  --label <LABEL>
+  --algorithm <ALGORITHM>
+  --material-stdin         read key material from stdin (to EOF)
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — store an SSH private key:**
+
+```bash
+relicario add key --title "Server deploy key" --label "id_ed25519" --algorithm ed25519 \
+  --material-stdin < ~/.ssh/id_ed25519
+```
+
+---
+
+### Document
+
+A file stored encrypted inside your vault. The `--file` flag is required; the file's bytes are encrypted and kept as an attachment on the item.
+
+```
+relicario add document --file <FILE> [OPTIONS]
+
+  --title <TITLE>
+  --file <FILE>    path to the file to encrypt and store (required)
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example:**
+
+```bash
+relicario add document --title "Passport scan" --file ~/Documents/passport.pdf
+```
+
+To get the file back out later: `relicario attachments "Passport scan"` to find the attachment ID, then `relicario extract "Passport scan" <AID> --out passport.pdf`. See [Attachments & Documents](attachments-and-documents.md) for more.
+
+---
+
+### TOTP
+
+A standalone TOTP authenticator entry (think: an item that generates the rotating 6-digit codes for two-factor login). If you want to attach a TOTP secret to an existing Login instead, use `--totp-qr` on `add login` or `edit`.
+
+```
+relicario add totp [OPTIONS]
+
+  --title <TITLE>
+  --issuer <ISSUER>
+  --label <LABEL>
+  --secret <SECRET>        base32-encoded TOTP secret (visible in shell history)
+  --secret-stdin           read TOTP secret from stdin (one line)
+  --period <PERIOD>        [default: 30]
+  --digits <DIGITS>        [default: 6]
+  --algorithm <ALGORITHM>  [default: sha1]
+  --group <GROUP>
+  --tags <TAGS>
+```
+
+**Example — add a TOTP entry, secret from stdin:**
+
+```bash
+echo "JBSWY3DPEHPK3PXP" | relicario add totp --title "GitHub 2FA" \
+  --issuer GitHub --label octocat --secret-stdin
+```
+
+Most services use the defaults (30-second period, 6 digits, SHA-1), so you usually only need `--issuer`, `--label`, and `--secret`/`--secret-stdin`. See [TOTP codes](totp.md) for how to view live codes.
+
+---
+
+## Viewing items
+
+### Get a single item
+
+```bash
+relicario get <QUERY>
+```
+
+`<QUERY>` is either an item ID or a **case-insensitive title substring** — so `relicario get github` finds any item with "github" in the title.
+
+By default, secret fields are **masked** (shown as `********`). Two flags change that:
+
+| Flag | Effect |
+|------|--------|
+| `--show` | Print all secret values in plaintext |
+| `--copy` | Copy the primary secret (Login password, Card number, etc.) to the clipboard — auto-clears after 30 seconds |
+
+**Examples:**
+
+```bash
+relicario get "Chase Sapphire"          # shows masked fields
+relicario get "Chase Sapphire" --show   # reveals card number and CVV
+relicario get "GitHub" --copy           # copies password; clears in 30s
+```
+
+### List all items
+
+```bash
+relicario list [OPTIONS]
+
+  --type <TYPE>    filter by item type (login, card, totp, …)
+  --group <GROUP>  filter by group label
+  --tag <TAG>      filter by tag
+  --trashed        show trashed items instead of live ones
+```
+
+**Examples:**
+
+```bash
+relicario list                   # all live items
+relicario list --type login      # logins only
+relicario list --group banking   # everything in the "banking" group
+relicario list --tag work        # everything tagged "work"
+```
+
+---
+
+## Editing items
+
+```bash
+relicario edit <QUERY>
+```
+
+Editing is interactive: Relicario shows each field's current value and lets you type a new one. **Leave a prompt blank and press Enter to keep the existing value.**
+
+For login items, you can update the linked TOTP secret from a QR code image:
+
+```bash
+relicario edit "GitHub" --totp-qr /path/to/qr.png
+```
+
+### Field history
+
+Relicario captures the previous value of secret fields whenever you change them (e.g., after a password rotation). To see that history:
+
+```bash
+relicario history <QUERY>                        # all captured changes, masked
+relicario history <QUERY> --show                 # reveal old values
+relicario history <QUERY> --field login_password # one field only
+```
+
+Field key examples: `login_password`, `card_number`, `totp_secret`.
+
+---
+
+## Deleting items
+
+Relicario has two deletion modes: **soft delete** (reversible, moves to trash) and **permanent purge**.
+
+### Soft delete and restore
+
+```bash
+relicario rm <QUERY>       # move to trash (reversible)
+relicario restore <QUERY>  # pull it back out of the trash
+```
+
+### Permanent purge
+
+```bash
+relicario purge <QUERY>    # delete the item AND all its attachments, forever
+```
+
+There is no undo for `purge`.
+
+### Trash management
+
+```bash
+relicario trash list    # see what's in the trash
+relicario trash empty   # permanently purge all items past the trash retention window
+```
+
+The retention window is configurable via `relicario settings trash-retention`.
+
+---
+
+**Next:** [Passwords & generators](passwords-and-generators.md)

user_docs/organizing.md

@@ -0,0 +1,162 @@
+# Organizing your vault: groups, tags, favorites, and search
+
+This page covers how to keep your vault tidy as it grows — sorting items into groups,
+tagging them for cross-cutting labels, marking favorites, and finding things quickly.
+
+---
+
+## Groups — one folder-like label per item
+
+A **group** is a single label that acts like a folder. Every item can belong to at most
+one group. Use groups for broad categories (a room in the house, a project, a person in
+the family).
+
+**Set a group when adding an item:**
+
+```
+relicario add login --title "Home router" --username admin --group Home
+relicario add card --title "Visa credit" --group Finance
+```
+
+**Change a group on an existing item:**
+
+Run `relicario edit <title-or-id>` and, when prompted for the group field, type the new
+value (or press Enter to keep the current one).
+
+**List items in a group:**
+
+```
+relicario list --group Home
+relicario list --group Finance
+```
+
+Group names are case-sensitive, so be consistent — `Home` and `home` are different groups.
+
+---
+
+## Tags — multiple labels per item
+
+**Tags** let you attach several labels to one item — useful when a single item fits more
+than one category. A login for your bank's app might belong to the `Finance` group and
+also carry tags `mobile` and `2fa-enabled`.
+
+**Set tags when adding an item** (comma-separated, no spaces around commas):
+
+```
+relicario add login --title "Bank mobile app" \
+    --username me@example.com \
+    --group Finance \
+    --tags mobile,2fa-enabled
+```
+
+**Change tags on an existing item:**
+
+Run `relicario edit <title-or-id>` and update the tags field when prompted.
+
+**Filter by tag:**
+
+```
+relicario list --tag mobile
+relicario list --tag 2fa-enabled
+```
+
+Only one tag at a time can be passed to `--tag`, but you can combine tag filtering with
+group and type filters (see [Combining filters](#combining-filters) below).
+
+---
+
+## Favorites — quick-access marker for login items
+
+Login items support a `--favorite` flag. Mark an item as a favorite when you add it:
+
+```
+relicario add login --title "Gmail" --username me@example.com --favorite
+```
+
+This is a quick-access marker — it shows up in the browser extension's favorites view so
+your most-used logins are always one click away.
+
+> To toggle a favorite on an existing login, run `relicario edit <title-or-id>` and
+> update the favorite field when prompted.
+
+---
+
+## Finding things
+
+### Find by title substring — `relicario get`
+
+`relicario get` accepts a title substring (case-insensitive) or an exact item id:
+
+```
+relicario get bank         # finds any item whose title contains "bank"
+relicario get a3f2c1      # finds the item with that id
+```
+
+Secrets are masked by default. Pass `--show` to reveal them, or `--copy` to copy the
+primary secret (Login password, Card number, etc.) to the clipboard — it clears
+automatically after 30 seconds.
+
+### Filter the full list — `relicario list`
+
+`relicario list` prints every item. Narrow it down with flags:
+
+| Flag | What it filters |
+|---|---|
+| `--type <TYPE>` | Item type: `login`, `secure-note`, `identity`, `card`, `key`, `document`, `totp` |
+| `--group <GROUP>` | Items in that group |
+| `--tag <TAG>` | Items carrying that tag |
+| `--trashed` | Trashed (soft-deleted) items only |
+
+### Combining filters
+
+All filters can be combined in one command:
+
+```
+# All login items in the Finance group tagged "2fa-enabled"
+relicario list --type login --group Finance --tag 2fa-enabled
+
+# Every trashed item in the Work group
+relicario list --group Work --trashed
+```
+
+---
+
+## A suggested scheme (non-prescriptive)
+
+There is no one right answer, but here is a pattern that works well for a household or
+small team:
+
+**Groups → broad areas of life.** Think of them like drawers:
+- `Home` — router, smart devices, alarm panel
+- `Finance` — bank accounts, investment logins, card numbers
+- `Work` — corporate VPN, project tools, SSH keys
+- `Personal` — social accounts, streaming services, email
+
+**Tags → cross-cutting traits** that apply across groups:
+- `2fa-enabled` — logins that have TOTP set up
+- `shared` — items you share with a family member
+- `critical` — accounts you would be in serious trouble losing
+
+**Favorites → your daily drivers.** Mark the five or ten logins you open every day.
+They surface at the top in the extension so you do not have to search.
+
+This keeps groups stable (you rarely add a new drawer) while tags stay flexible (add new
+ones whenever a new trait comes up).
+
+---
+
+## Shell-completion tip
+
+If you build the optional shell completions, `--group` autocompletes from a local cache
+that Relicario maintains. Run:
+
+```
+relicario completions bash > /etc/bash_completion.d/relicario   # bash
+relicario completions zsh > ~/.zfunc/_relicario                  # zsh
+```
+
+After that, pressing Tab after `--group` suggests your existing group names.
+
+---
+
+**Next:** [Sync & backup](sync-and-backup.md)

user_docs/passwords-and-generators.md

@@ -0,0 +1,152 @@
+# Generating strong passwords & passphrases
+
+This page covers how to generate passwords and word passphrases with Relicario, how to check the strength of a candidate passphrase, and how to save your preferred generator settings so you never have to repeat yourself.
+
+---
+
+## Two modes: random characters vs. word passphrases
+
+`relicario generate` has two modes:
+
+| Mode | What you get | When to use it |
+|---|---|---|
+| Random characters (default) | `x7#Kp!mQr9Ew2@LnVdZ` | Site passwords, API keys, anything with a character limit |
+| BIP39 word passphrase (`--bip39`) | `olive bridge furnace tangle whisper` | Your vault passphrase, disk encryption, anywhere you have to type it by hand |
+
+---
+
+## Quick examples
+
+Generate a random 20-character password (default settings):
+
+```
+relicario generate
+```
+
+Generate a longer, 32-character password:
+
+```
+relicario generate -l 32
+```
+
+Generate a 6-word BIP39 passphrase:
+
+```
+relicario generate --bip39 -w 6
+```
+
+Generate a BIP39 passphrase with dashes between words instead of spaces:
+
+```
+relicario generate --bip39 --separator -
+```
+
+---
+
+## All flags
+
+```
+relicario generate [-l/--length N] [--bip39] [-w/--words N] [--symbols <SET>] [--separator <S>]
+```
+
+| Flag | What it does |
+|---|---|
+| `-l`, `--length N` | Total length of the random-character password |
+| `--bip39` | Switch to BIP39 word-passphrase mode |
+| `-w`, `--words N` | Number of BIP39 words to include |
+| `--symbols <SET>` | Symbol set: `safe`, `extended`, or a custom literal (e.g. `!@#`) |
+| `--separator <S>` | Word separator for BIP39 mode (e.g. a dash or an underscore) |
+
+### About `--symbols`
+
+- **`safe`** — a conservative set that works on most sites without paste-rejection headaches.
+- **`extended`** — a broader set of symbols for maximum entropy when sites permit it.
+- **custom literal** — pass exactly the characters you want, e.g. `--symbols '!@#'`.
+
+---
+
+## Defaults
+
+Outside a vault, the built-in defaults are:
+
+- Random mode: length **20**, symbol set **safe**
+- BIP39 mode: **5** words, separator **space**
+
+Inside an initialized vault, any flag you leave off falls back to your **saved generator defaults** (see below). This means `relicario generate` inside your vault already "knows" your preferences — you only have to set them once.
+
+---
+
+## Saving your generator defaults
+
+Run this once inside your vault directory. Any flag you pass gets saved; flags you omit stay at their current value.
+
+Switch to BIP39 mode and use 6 words by default:
+
+```
+relicario settings generator-defaults --bip39 --words 6
+```
+
+Switch to random-character mode with length 24 and extended symbols:
+
+```
+relicario settings generator-defaults --random --length 24 --symbols extended
+```
+
+Set a custom word separator for BIP39 mode:
+
+```
+relicario settings generator-defaults --bip39 --separator -
+```
+
+Full flag reference for `settings generator-defaults`:
+
+| Flag | What it does |
+|---|---|
+| `--random` | Switch the saved default mode to random-character |
+| `--bip39` | Switch the saved default mode to BIP39 passphrase |
+| `--length N` | Random mode: default password length |
+| `--words N` | BIP39 mode: default number of words |
+| `--symbols <SET>` | Random mode: default symbol charset (`safe`, `extended`, or a custom literal) |
+| `--separator <S>` | BIP39 mode: default word separator |
+
+To see all current settings (including your saved generator defaults), run:
+
+```
+relicario settings show
+```
+
+---
+
+## Checking a passphrase's strength
+
+Before committing to a passphrase, you can score it:
+
+```
+relicario rate "olive bridge furnace tangle whisper sunset"
+```
+
+Or pipe it in from stdin (keeps it out of your shell history — recommended):
+
+```
+relicario rate -
+```
+
+Relicario prints a **score from 0 to 4** and an estimated number of guesses. Higher is better; aim for a 4 for anything important.
+
+> **Informational only.** The `rate` command does not block you from using a weak passphrase. It is purely a tool to help you make an informed choice.
+
+---
+
+## A note on your vault passphrase
+
+Your **vault passphrase** is Factor 1 of your two-factor encryption — the thing you type to unlock everything. A few things worth knowing:
+
+- Make it **strong and memorable**. You cannot reset it if you forget it (there is no recovery path for a lost passphrase — see [Recovery](recovery.md) for the full picture).
+- A BIP39 word passphrase is a great choice: easy to write down and type, hard to guess. Generate a few candidates with `relicario generate --bip39` and use `relicario rate` to compare them.
+- Your passphrase is always entered locally, at a hidden prompt. It never leaves your device.
+
+For a plain-language explanation of why both your passphrase AND your reference image are required to unlock your vault, see [Concepts](concepts.md).
+
+---
+
+**Next:** [Two-factor codes (TOTP)](totp.md)

user_docs/recovery.md

@@ -0,0 +1,81 @@
+# Recovery — if something goes wrong
+
+This page covers what you can do when you lose access to your vault, what Relicario can recover, and — just as importantly — what it cannot.
+
+---
+
+## The two factors, plainly stated
+
+Unlocking your Relicario vault always requires two things working together:
+
+- **Factor 1 — your passphrase.** The phrase you type every time you unlock. Only you know it; it is never stored anywhere.
+- **Factor 2 — your reference image.** The JPEG photo you chose at setup. Relicario hid a random secret inside its pixels. You keep this file yourself; it is intentionally excluded from your git repository.
+
+Relicario mixes these two factors together to derive the key that decrypts your data. Neither factor alone is enough. If either one is missing or wrong, the vault cannot open.
+
+---
+
+## The Recovery QR — your offline backup of Factor 2
+
+The Recovery QR is a safety net for your reference image secret. Think of it as a printable backup of Factor 2, sealed shut by Factor 1.
+
+Here is what that means in practice:
+
+- **It is encrypted.** The QR encodes your image secret locked behind your passphrase. Someone who finds your printed QR still needs your passphrase to use it.
+- **It is not saved to disk.** Relicario prints it to your terminal as text art and then forgets it. You must print or photograph it immediately.
+- **Storing it offline (paper, safe) is the point.** A digital copy on the same device as your reference image does not add much protection.
+
+### Making a Recovery QR
+
+Run this inside your vault directory:
+
+```
+relicario recovery-qr generate
+```
+
+Relicario will read your reference image, ask for your vault passphrase, and print a QR code as ASCII art in the terminal. The code is **not written to any file**. Print it, photograph it, or copy the text — then store it somewhere safe and offline (a fireproof safe, a safety deposit box, a trusted family member's home).
+
+### Using a Recovery QR (advanced / last resort)
+
+If you have lost your reference image but still have the printed QR and your passphrase:
+
+```
+relicario recovery-qr unwrap
+```
+
+Paste the base64 payload you scanned from the QR, then enter your passphrase. Relicario prints the recovered image secret as a hex string.
+
+Think of this as a safe for the secret itself, not a one-click restore: it proves your Factor 2 can be recovered as long as you keep the QR **and** remember your passphrase. Turning that raw secret back into a ready-to-use reference image is an advanced step — so for everyday peace of mind, the simplest safety net is to keep a spare copy of your reference image (or an [`--include-image` backup archive](sync-and-backup.md)). Then "recovery" is just putting the file back and unlocking as usual.
+
+---
+
+## The hard truth
+
+There is no password reset. There is no backdoor. Not even the project authors can recover your data. This is intentional — it is what ensures the server hosting your git repository can never read your vault, even under legal compulsion.
+
+Here is what happens in each loss scenario:
+
+| What you lose | Result |
+|---|---|
+| Your **passphrase** (even with both the reference image and the recovery QR) | **Unrecoverable.** The recovery QR is itself locked by your passphrase. No passphrase means nothing can be decrypted. |
+| Your **reference image AND your recovery QR** (even if you remember the passphrase) | **Unrecoverable.** The image secret is gone. Without it, the two-factor key derivation cannot complete. |
+| Only your **reference image** (but you have a printed recovery QR) | Recoverable — use `relicario recovery-qr unwrap` as described above. |
+| Only your **recovery QR** (but you still have the reference image file) | No problem. Your reference image is your active Factor 2. Make a fresh recovery QR when you can. |
+
+The underlying principle: losing both factors — your passphrase and your image secret — means the data is gone for good. This is not a limitation to be patched; it is the security guarantee that protects your data from everyone, including the people who wrote Relicario.
+
+---
+
+## Do this now — a short checklist
+
+Before you need any of this:
+
+- [ ] **Back up your reference image.** Copy `reference.jpg` (or whatever you named it) to at least one location that is separate from your computer — an encrypted external drive, a USB stick stored safely offline, or a secure cloud backup you control. Your git remote does **not** contain it; the file is gitignored by design.
+- [ ] **Print a Recovery QR.** Run `relicario recovery-qr generate`, print the output, and store the paper copy somewhere you would still find it if your devices were all lost or destroyed.
+- [ ] **Confirm you can recall your passphrase.** If you are not confident, consider whether your memorization strategy is reliable. There is no recovery path for a forgotten passphrase.
+
+For guidance on encrypted `.relbak` backup archives (which can optionally bundle the reference image), see [Sync & backup](sync-and-backup.md).
+
+---
+
+**Next:** [FAQ](faq.md)

user_docs/sync-and-backup.md

@@ -0,0 +1,110 @@
+# Syncing across devices & backing up
+
+This page covers how to keep your vault in sync across machines, how to create a portable encrypted backup, and why you need more than just your git remote to have a full backup.
+
+---
+
+## Syncing your vault between devices
+
+Relicario stores your vault in a git repo. Every item you add, edit, or delete is committed there. To push your latest changes to another machine (or pull a teammate's changes), run:
+
+```
+relicario sync
+```
+
+Under the hood, this does a `git pull --rebase` followed by a push to your configured git remote — the same remote you set up when you initialized your vault. Any machine that has the vault cloned and a copy of your reference image can sync and stay up to date.
+
+**Check what's in your vault at a glance:**
+
+```
+relicario status
+```
+
+This prints a summary: how many items and attachments you have, and the timestamp of the last commit.
+
+---
+
+## Why your git remote alone is NOT a full backup
+
+Here is the catch: your reference image — the photo that carries your second factor — is **gitignored**. It never gets committed to your git repo, by design. If someone stole your git remote, they still could not decrypt anything without that image.
+
+But that also means: **if you back up only your git remote and lose your reference image, you cannot unlock your vault.** The two factors travel separately by design.
+
+A complete backup has two parts:
+1. Your git remote (all the encrypted vault data).
+2. A safe copy of your reference image (the second factor).
+
+---
+
+## Creating a portable encrypted backup
+
+For the safest kind of backup — one you can carry on a USB drive or store in a separate location — use `relicario backup export`. This packs your entire vault into a single encrypted `.relbak` file. You set a **separate backup passphrase** that is independent of your vault passphrase, so the `.relbak` file can be kept and shared separately without revealing your vault credentials.
+
+**Export a backup:**
+
+```
+relicario backup export vault-backup.relbak
+```
+
+You will be prompted to set a backup passphrase. This is not the same as your vault passphrase — choose something strong and store it safely.
+
+**Include your reference image in the backup** (making it fully self-contained):
+
+```
+relicario backup export vault-backup.relbak --include-image
+```
+
+With `--include-image`, the `.relbak` file contains everything needed to restore and unlock the vault. If your reference image lives somewhere other than the default `reference.jpg` in the vault directory, point to it explicitly:
+
+```
+relicario backup export vault-backup.relbak --include-image --image /path/to/your/reference.jpg
+```
+
+**Skip the git history** (smaller file, useful for quick snapshot backups):
+
+```
+relicario backup export vault-backup.relbak --no-history
+```
+
+**Restore from a backup:**
+
+```
+relicario backup restore vault-backup.relbak
+```
+
+Or restore into a specific directory:
+
+```
+relicario backup restore vault-backup.relbak /path/to/new-vault/
+```
+
+The target directory must not already contain a `.relicario/` folder — Relicario will stop and tell you if it does.
+
+---
+
+## Importing from LastPass
+
+If you are migrating from LastPass, Relicario can import your data directly from a LastPass CSV export. Unlock your vault first, then run:
+
+```
+relicario import lastpass lastpass-export.csv
+```
+
+Each row in the CSV becomes a new item. If a row cannot be parsed, it is skipped and the reason is printed to the terminal — the rest of the import continues. Title collisions are kept as separate items (no automatic deduplication).
+
+---
+
+## Backup checklist
+
+> **Before you feel safe, make sure you have all four of these:**
+
+- [ ] **Your git remote** is reachable and has your latest sync (`relicario sync` before stepping away from a machine).
+- [ ] **A safe copy of your reference image** stored somewhere independent of the vault — a USB drive, an encrypted cloud folder, or a printed recovery QR (see [Recovery](recovery.md)).
+- [ ] **Optionally, a `.relbak` file with `--include-image`** stored somewhere offsite. This is the most convenient full restore path — one file, one backup passphrase.
+- [ ] **Your vault passphrase** memorized. There is no reset and no backdoor.
+
+For the full picture on what happens if you lose a factor, and how to generate a recovery QR for your reference image, see [Recovery](recovery.md).
+
+---
+
+**Next:** [The browser extension](the-browser-extension.md)

user_docs/the-browser-extension.md

@@ -0,0 +1,163 @@
+# The Browser Extension
+
+This page covers how to build and install the Relicario browser extension, set it up for the first time, and use it for everyday password unlocking, autofill, and vault management.
+
+---
+
+## What it is
+
+The Relicario browser extension brings your vault into your browser. It works in **Chrome and Chromium** (the primary target) and **Firefox** (Manifest V3). It gives you a popup for quick unlock, search, and field copying; in-page autofill on login forms; live TOTP codes; and, on Chrome, a fullscreen vault tab where you can add, edit, and manage everything.
+
+There is no listing in the Chrome Web Store or Firefox Add-ons yet — you build and load it from source.
+
+---
+
+## Build it from source
+
+You need the Relicario source code and [Node.js](https://nodejs.org) available in your terminal. Open a terminal in the root of the Relicario source tree and run these commands in order:
+
+```bash
+# Step 1 — build the WebAssembly crypto module
+npm run build:wasm
+
+# Step 2 — build the Chrome extension (output goes to extension/dist/)
+npm run build
+```
+
+If you also want a Firefox build:
+
+```bash
+npm run build:firefox
+# Output goes to extension/dist-firefox/
+```
+
+To build everything in one shot:
+
+```bash
+npm run build:all
+```
+
+---
+
+## Install it in your browser
+
+### Chrome / Chromium
+
+1. Go to `chrome://extensions` in the address bar.
+2. Turn on **Developer mode** (toggle in the top-right corner).
+3. Click **Load unpacked**.
+4. Select the `extension/dist/` folder inside the Relicario source tree.
+
+The Relicario icon should appear in your browser toolbar.
+
+### Firefox
+
+1. Go to `about:debugging#/runtime/this-firefox` in the address bar.
+2. Click **Load Temporary Add-on**.
+3. Navigate to `extension/dist-firefox/` and select the `manifest.json` file inside it.
+
+> **Note:** Firefox loads extensions temporarily — they are removed when you close and reopen the browser. Rebuild and reload after each browser restart.
+
+---
+
+## First-run setup wizard
+
+The first time you click the Relicario toolbar icon, a short setup wizard walks you through connecting the extension to a vault.
+
+### Option A — Create a new vault
+
+1. Choose **Create a new vault**.
+2. Select your git host: **Gitea** or **GitHub**. Enter the host URL (for Gitea), your repository, and an access token.
+3. Upload a carrier photo — any JPEG you own. Relicario will embed a hidden 256-bit secret inside it and produce a **reference image**. Set a strong passphrase (a strength meter guides you; you need a high score to proceed).
+4. Relicario creates the vault in your remote repository and stores the reference image inside the browser. The reference image is your second factor — it never leaves the browser or goes to your git remote.
+5. Give this device a name (e.g. "Laptop") and click **Done**.
+
+### Option B — Attach this device to an existing vault
+
+1. Choose **Attach to existing vault**.
+2. Enter your git host details (host URL, repository, access token).
+3. Upload your existing reference JPEG — the one produced when the vault was first created.
+4. Enter your passphrase.
+5. Give this device a name and click **Done**.
+
+---
+
+## Everyday use
+
+Click the Relicario toolbar icon. Type your passphrase and click **Unlock**.
+
+You only type your passphrase — the reference image is stored once in the browser and re-read automatically on every unlock. All cryptography runs on-device inside WebAssembly; nothing secret is sent over the network.
+
+Once unlocked, the popup shows your item list. You can:
+
+- **Search** by typing any part of an item's title.
+- **Reveal or copy** fields (passwords, card numbers, notes, etc.).
+- **View live TOTP codes** — they count down and refresh every 30 seconds.
+
+When you're done, close the popup. The vault locks automatically based on your configured idle timeout (see [Auto-lock](#auto-lock) below).
+
+---
+
+## Autofill
+
+When you land on a login page, Relicario shows a small icon inside the username or password field. Click it to fill the matching login.
+
+Matching is done by **hostname** — Relicario looks for a login whose URL matches the current page's hostname.
+
+**The first time you use autofill on a site**, Relicario shows a Trust-On-First-Use prompt asking you to confirm. Once you confirm, it remembers.
+
+**On form submit**, Relicario can offer to **save a new login** or **update an existing one** if it detects that the credentials differ from what it has stored.
+
+> **Heads-up on hostname matching:** matching is coarse. `github.com` and `www.github.com` are treated as separate hosts, so a login saved for one will not autofill on the other. You can add both URLs to a login item to cover both.
+
+**Syncing** is always manual — click **Sync now** in the popup. There is no background polling.
+
+---
+
+## The fullscreen vault tab (Chrome only)
+
+On Chrome, you can open a **fullscreen vault tab** for complete vault management. This is not available in Firefox.
+
+From the fullscreen tab you can:
+
+- **Add, edit, and delete** all 7 item types: Login, Secure Note, Identity, Card, SSH/API Key, Document, and TOTP.
+- Manage **settings**, **devices**, **trash**, and **field history**.
+- Run a **backup export or restore** (`.relbak` files).
+- **Import from LastPass** (CSV export).
+
+For day-to-day password filling the popup is enough; the fullscreen tab is for vault housekeeping.
+
+---
+
+## Permissions the extension requests
+
+| Permission | Why |
+|---|---|
+| `storage` | Saves your configuration and the reference image inside the browser. |
+| `activeTab` | Reads the current tab's URL to match logins for autofill. |
+| `clipboardWrite` | Copies secrets to the clipboard when you click Copy. |
+| Host access | Injects the autofill icon into login pages; communicates with your Gitea/GitHub API for sync. |
+
+---
+
+## Auto-lock
+
+You can configure an idle timeout in the extension settings. Options include locking after N minutes of inactivity, or locking immediately when the popup closes. To change it, open the popup while unlocked and look for **Settings → Auto-lock**.
+
+---
+
+## Current limits
+
+A few things to be aware of before you rely on the extension:
+
+- **No org/enterprise vault support.** If you use Relicario's multi-user org vault, the extension cannot browse, read, or write to it yet. Org support is planned but has no release date.
+- **Fullscreen vault tab is Chrome-only.** Firefox users get the popup and autofill, but not the full management UI.
+- **Hostname matching is coarse.** `github.com` and `www.github.com` are separate entries. Save both URLs on a login item if you need both covered.
+- **One vault per browser install.** You cannot switch between personal vaults in the same browser profile.
+- **Sync is manual.** There is no push/pull happening in the background — you initiate sync by clicking **Sync now**.
+- **No mobile apps.** The extension is desktop-browser only.
+- **No Relicario-run server.** You need your own Gitea instance or a GitHub account. Relicario does not provide hosted storage.
+
+---
+
+**Next:** [Recovery](recovery.md)

user_docs/totp.md

@@ -0,0 +1,124 @@
+# Two-factor (TOTP) codes
+
+This page covers how to store TOTP authenticator secrets in Relicario and view live codes in the browser extension.
+
+---
+
+## What is a TOTP code?
+
+When a website offers "two-factor authentication" or "authenticator app" support, it gives you a short secret — usually as a QR code — that your authenticator app uses to generate a fresh 6-digit code every 30 seconds. Those rolling codes are called TOTP codes (Time-based One-Time Passwords).
+
+Relicario can store that secret alongside your login, so you never have to hunt for a separate app. The browser extension then shows live codes that tick down in real time, right next to your password.
+
+---
+
+## Where to find the TOTP secret on a website
+
+Look for any of these on the site's security or two-factor settings page:
+
+- A QR code labeled something like "Scan with your authenticator app"
+- A text link or button that says "Can't scan the QR code?", "Enter key manually", or "Show secret key"
+
+The manual key is a string of letters and numbers (Base32 encoded — it looks like `JBSWY3DPEHPK3PXP`). You can use either the QR image file or that manual key with Relicario.
+
+Keep this secret safe. Anyone who has it can generate codes for your account.
+
+---
+
+## Two ways to add a TOTP secret
+
+### Option 1 — Standalone TOTP item
+
+Use this when the account is purely authenticator-based and you don't have a separate login item for it, or when you just want to keep the TOTP separate.
+
+```
+relicario add totp --title "GitHub 2FA" --issuer "GitHub" --label "you@example.com"
+```
+
+Relicario will prompt for the Base32 secret at a hidden prompt. Or pass it via flag or stdin:
+
+```
+# Pass the secret as a flag (shows in your shell history — prefer the prompt or --secret-stdin)
+relicario add totp --title "GitHub 2FA" --issuer "GitHub" --label "you@example.com" \
+  --secret JBSWY3DPEHPK3PXP
+
+# Read it from stdin (keeps it out of shell history)
+echo "JBSWY3DPEHPK3PXP" | relicario add totp --title "GitHub 2FA" --issuer "GitHub" \
+  --label "you@example.com" --secret-stdin
+```
+
+Available flags for `relicario add totp`:
+
+| Flag | Default | What it sets |
+|---|---|---|
+| `--title <TITLE>` | prompted | Item name shown in the vault |
+| `--issuer <ISSUER>` | prompted | Service name (e.g. `GitHub`) |
+| `--label <LABEL>` | prompted | Account identifier (e.g. your email) |
+| `--secret <SECRET>` | prompted | Base32-encoded TOTP secret |
+| `--secret-stdin` | — | Read secret from stdin instead of prompting |
+| `--period <PERIOD>` | `30` | Code rotation interval in seconds |
+| `--digits <DIGITS>` | `6` | Code length |
+| `--algorithm <ALGORITHM>` | `sha1` | Hash algorithm |
+| `--group <GROUP>` | — | Folder-like label |
+| `--tags <TAGS>` | — | Comma-separated tags |
+
+Most sites use the defaults (30 seconds, 6 digits, SHA-1). Only change these if the site's setup instructions specifically say otherwise.
+
+### Option 2 — Attach TOTP to an existing Login item
+
+If you already have (or are creating) a login item for the site, you can attach the TOTP secret directly to it using a QR image file.
+
+**At creation time:**
+
+```
+relicario add login --title "GitHub" --username "you@example.com" \
+  --totp-qr /path/to/github-totp-qr.png
+```
+
+**On an existing login:**
+
+```
+relicario edit "GitHub" --totp-qr /path/to/github-totp-qr.png
+```
+
+The `--totp-qr <PATH>` flag decodes the `otpauth://` QR image and stores the TOTP secret on the login item. No manual typing of the secret required.
+
+---
+
+## Viewing live codes
+
+**In the browser extension:** open the popup and find your TOTP or login item. The extension shows the current 6-digit code with a countdown timer. The code refreshes automatically every 30 seconds. See [The browser extension](the-browser-extension.md) for how to install and use the extension.
+
+**From the CLI:** the CLI stores the secret but does not display live rotating codes. Run `relicario get "GitHub"` to see the item (the TOTP secret is masked by default; add `--show` to reveal the stored secret).
+
+---
+
+## Changing or rotating a TOTP secret
+
+If a site asks you to reset your authenticator (or you're migrating to a new device), run:
+
+```
+relicario edit "GitHub"
+```
+
+Relicario prompts you for each field. Press Enter to keep the current value; type (or paste) the new secret when you reach the TOTP secret field. To set it from a new QR image instead:
+
+```
+relicario edit "GitHub" --totp-qr /path/to/new-qr.png
+```
+
+The old secret is automatically captured in field history before it's overwritten. To review previous secrets:
+
+```
+relicario history "GitHub" --field totp_secret
+```
+
+Add `--show` to reveal the masked values:
+
+```
+relicario history "GitHub" --field totp_secret --show
+```
+
+---
+
+**Next:** [Attachments & documents](attachments-and-documents.md)