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/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)