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