docs(user): add user_docs/ end-user guide (12 pages)

A friendly, task-oriented guide for non-technical users: README index,
getting-started, concepts, items, passwords-and-generators, totp,
attachments-and-documents, organizing, sync-and-backup, the-browser-extension,
recovery, faq. Every command/flag derived from the actual CLI surface
(`relicario --help` tree) and real extension behavior — no invented flags.
Org item-type parity is covered high-level pending the v0.8.1 B/C merge
(two TODO markers left for the rebase).

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)