feat(guides): add new key management, categories, and IM guides

- add Instant Messaging guide covering IM encrypt/sign and phrases
- add Key Categories guide describing category creation and usage
- add Manage Your Keys guide detailing key list, bulk ops, and actions

4 files changed, 400 insertions, 0 deletions

diff --git a/src/content/docs/guides/instant-messaging.mdx b/src/content/docs/guides/instant-messaging.mdx
new file mode 100644
index 0000000..254c12a
--- /dev/null
+++ b/src/content/docs/guides/instant-messaging.mdx
@@ -0,0 +1,124 @@
+---
+title: "Instant Messaging"
+description: "Turn an encrypted message into one short line you can paste into any chat app, and share a secret phrase so your messages do not stand out."
+sidebar:
+  label: Instant Messaging
+  order: 7
+---
+
+import { Steps } from "@astrojs/starlight/components";
+
+Normal encrypted text is a big block that starts with `-----BEGIN PGP
+MESSAGE-----`. It is obvious at a glance, it is long, and chat apps often
+break it by adding line breaks or turning parts of it into links.
+
+**Instant messaging** solves that. It turns your encrypted message into a
+single short line of letters and numbers that pastes cleanly into any chat
+app, and that does not announce what it is.
+
+:::note[New in v2.2.2]
+
+Instant messaging was added in GpgFrontend v2.2.2.
+
+:::
+
+## Send a Message
+
+<Steps>
+
+1. Type your message in the Text Editor.
+
+2. Tick the person you are writing to in the Key Toolbox.
+
+3. Choose **Operations**, then **IM Encrypt**. The shortcut is **Ctrl+M**.
+
+</Steps>
+
+Your text is replaced by one long line. Copy it and paste it into your chat
+app.
+
+If you also want the other person to know the message really came from you,
+use **IM Encrypt & Sign** instead. The shortcut is **Ctrl+Shift+M**.
+
+:::tip[Put the buttons on the toolbar]
+
+Open **Settings**, go to **Appearance**, and tick **IM Encrypt** or **IM
+Encrypt Sign** under **Actions**. The buttons then sit in the Operations Bar
+with the others.
+
+:::
+
+## Read a Message
+
+Paste the line into the Text Editor and press **Decrypt**, exactly as you
+would for any other message. GpgFrontend works out on its own that it is an
+instant message.
+
+There is no separate button for reading one. If the sender signed it, use
+**Decrypt & Verify** to check the signature too.
+
+## Share a Secret Phrase
+
+Out of the box, your messages still look like nothing in particular to most
+people. But anyone who knows GpgFrontend can recognise them for what they are.
+
+To stop that, you and the person you write to can share a **secret phrase**.
+Once you both have the same one, your messages look like plain random text to
+everyone else.
+
+<Steps>
+
+1. Open **Settings** and go to **Instant Messaging**.
+
+2. Click **Generate**. A long phrase appears.
+
+3. Click **Copy** and send the phrase to your friend privately. Not over the
+   chat app you are trying to protect.
+
+4. Your friend opens the same page and clicks **Paste**.
+
+5. You both look at the **Book Fingerprint**, a short code such as
+   `3F9A-1C4E`. Read it out to each other. If the two codes match, you are
+   set.
+
+</Steps>
+
+The fingerprint is safe to say out loud or send anywhere. The phrase is not.
+
+:::caution[You must both use exactly the same phrase]
+
+If the phrases do not match, your friend cannot read your messages at all.
+The fingerprint check exists so you catch this straight away.
+
+:::
+
+### What Happens Without a Phrase
+
+Nothing breaks. Your message is still properly encrypted, and only the person
+you sent it to can read it.
+
+The only thing you lose is the disguise. Without a shared phrase, GpgFrontend
+falls back to a built-in one that every copy of the program has, so anyone who
+knows the program can tell your message is an encrypted GpgFrontend message.
+
+The first time you use IM Encrypt without a phrase, the program says so and
+offers to take you to the settings page.
+
+## If the Message Is Too Long
+
+Instant messages are meant for short notes. If yours is too long, GpgFrontend
+tells you and does nothing.
+
+Either shorten the text, or send it the normal way with **Encrypt**. There is
+no length limit on a normal encrypted message.
+
+## Good to Know
+
+- The shared phrase hides **what kind** of message you are sending. It is not
+  what keeps the message secret. Your OpenPGP keys do that, with or without a
+  phrase.
+- The phrase is stored in GpgFrontend's own protected storage, not in a plain
+  settings file.
+- One phrase covers everyone you use it with. If you want to keep two
+  conversations apart, you need a phrase per person, and you have to change it
+  in settings when you switch.
diff --git a/src/content/docs/guides/key-categories.mdx b/src/content/docs/guides/key-categories.mdx
new file mode 100644
index 0000000..bf2e6cf
--- /dev/null
+++ b/src/content/docs/guides/key-categories.mdx
@@ -0,0 +1,114 @@
+---
+title: "Key Categories"
+description: "Sort your keys into named, coloured categories so a long key list stays easy to work with."
+sidebar:
+  label: Key Categories
+  order: 14
+---
+
+import { Steps } from "@astrojs/starlight/components";
+
+Once you have a lot of keys, finding the right one takes longer than it should.
+A **category** is a label you put on keys to tidy them up, such as `Work`,
+`Family`, or `Servers`.
+
+A category changes nothing about the keys themselves. It only changes what you
+see.
+
+:::note[Not the same as a key group]
+
+A **key group** is a shortcut for encrypting to several people at once, and it
+shows up in the key list as something you can pick as a recipient.
+
+A **category** never does that. It is only a way of sorting the list. See
+[Key Group](/guides/key-group/) if that is what you are after.
+
+:::
+
+## Where to Find Them
+
+Categories appear in two places:
+
+- **Key Management window**: a list down the left side. This is where you
+  create and change them.
+- **Key Toolbox** in the main window: a thin coloured strip. You can switch
+  between categories here, but not edit them.
+
+Clicking a category shows only the keys in it.
+
+## The Ready-Made Ones
+
+Some categories are always there and fill themselves in:
+
+- **All**: every key.
+- **Has Private Key**: keys you own.
+- **Only Public Key**: other people's keys.
+- **Key Group**: your key groups.
+- **Expiring Soon**: keys that run out in the next 30 days.
+- **Expired**, **Revoked**, **Disabled**, **No Primary Key**: keys with a
+  problem.
+
+You cannot rename or delete these.
+
+:::tip[Change what "soon" means]
+
+Open **Settings**, go to **General**, and set **Warn about keys expiring
+within** to any number of days you like.
+
+:::
+
+## Make Your Own
+
+<Steps>
+
+1. Open the **Key Management** window.
+
+2. Click the **+** button at the bottom of the category list.
+
+3. Type a name and click OK.
+
+4. Pick a colour if you want one, or just click Cancel to get an automatic
+   one.
+
+</Steps>
+
+## Put Keys in a Category
+
+<Steps>
+
+1. Find the key in the key list. Select several at once if you like.
+
+2. Right-click it and open the **Category** submenu.
+
+3. Tick the category you want.
+
+</Steps>
+
+To take a key out again, go to that category, right-click the key, and choose
+**Remove From This Category**.
+
+A key can be in as many categories as you like.
+
+## Rename, Recolour, Reorder
+
+Right-click a category you made for **Rename Category**, **Set Colour**, and
+**Reset Colour**.
+
+To change the order, drag a category up or down the list. The order is
+remembered.
+
+**Delete Category** removes the label only. Your keys are never touched.
+
+:::note[Where the Favourite tab went]
+
+GpgFrontend v2.2.2 replaced the old **Favourite** tab with categories. Old
+favourites are not carried over, so make a category and put those keys back in
+it.
+
+:::
+
+## Good to Know
+
+- Categories belong to one key database. If you use more than one, each has
+  its own set. See [Multi-Key Database](/advanced/key-database/).
+- The search box searches inside the category you are looking at.
diff --git a/src/content/docs/guides/key-group.md b/src/content/docs/guides/key-group.md
index 76777bc..2bea9b7 100644
--- a/src/content/docs/guides/key-group.md
+++ b/src/content/docs/guides/key-group.md
@@ -1,12 +1,24 @@
 ---
 title: Key Groups
 description: "Create and use key groups in GpgFrontend to encrypt to multiple recipients at once, treating a collection of public keys as a single key."
+sidebar:
+  label: Key Group
+  order: 13
 ---
 
 A Key Group lets you bundle many public keys together and use them as one key.
 This makes it easy to send an encrypted message or file to several people at the
 same time.
 
+:::note[Not the same as a key category]
+
+A key group is something you can **encrypt to**. It behaves like a key.
+
+A [key category](/guides/key-categories/) only tidies up your key list. You
+cannot encrypt to one.
+
+:::
+
 ## What is a Key Group?
 
 Think of a Key Group as a mailing list for encryption. You give the group a name
diff --git a/src/content/docs/guides/key-management.mdx b/src/content/docs/guides/key-management.mdx
new file mode 100644
index 0000000..803bede
--- /dev/null
+++ b/src/content/docs/guides/key-management.mdx
@@ -0,0 +1,150 @@
+---
+title: "Manage Your Keys"
+description: "Use the Key Management window to find, copy, export, certify, and renew your OpenPGP keys, one at a time or in bulk."
+sidebar:
+  label: Manage Keys
+  order: 12
+---
+
+import { Steps } from "@astrojs/starlight/components";
+
+The **Key Management** window is where you look after your keys. Open it with
+the **Manage Keys** button in the toolbar.
+
+The Key Toolbox in the main window and this window show the same keys, but they
+are for different jobs. The Toolbox is for **picking** a key for a task. This
+window is for **doing something to** a key.
+
+## What You Are Looking At
+
+Three parts:
+
+- **Down the left**: your categories. Click one to show only those keys. See
+  [Key Categories](/guides/key-categories/).
+- **In the middle**: your keys, one per row.
+- **Above the list**: buttons for refreshing, ticking keys, choosing columns,
+  and switching key database.
+
+## Find a Key
+
+Type in the search box at the top. It looks at the name, the email address, the
+key ID, and the fingerprint, so any of those will find the key.
+
+You can paste a fingerprint with spaces in it and it still matches.
+
+- **Ctrl+F** jumps to the search box.
+- **Escape** clears it.
+- Click a column heading to sort by it. Click again to reverse it.
+
+## The Line Along the Bottom
+
+The bottom of the window keeps a running count: how many keys you have, how
+many you own the private half of, how many run out soon, and how many have
+expired or been revoked.
+
+It is the quickest way to notice that something needs your attention. If it
+says a key is expiring soon, the **Expiring Soon** category shows you which
+one.
+
+## Right-Click a Key
+
+This is where most of the work happens. Right-click any key for a menu of
+things you can do to it. All of this is new in v2.2.2.
+
+### Look at it
+
+- **Show Key Details**: everything about the key. See
+  [Key Pair Details](/guides/view-keypair-info/).
+
+### Copy something
+
+- **Copy Fingerprint**: the long code people use to check they have the right
+  key. This is the one to read out over the phone.
+- **Copy Key ID**: the short code. Easier to type, but less exact.
+- **Copy Email**: the address on the key.
+- **Copy Public Key Block**: the whole public key as text, ready to paste into
+  an email or a web page.
+
+### Save it to a file
+
+- **Export Public Key...**: saves the half you can safely give away.
+- **Export Private Key...**: saves the half you must keep.
+
+:::caution[Be careful with the private one]
+
+A private key file is your identity. Anyone who gets it can read messages sent
+to you and sign things as you.
+
+Save it somewhere only you can reach, such as an encrypted drive, and never
+send it anywhere.
+
+:::
+
+### Change it
+
+- **Set Expiry...**: change when the key runs out, or stop it expiring.
+- **Certify Key...**: sign someone else's key to say you have checked it is
+  really theirs. See
+  [Trust Chain Management](/guides/openpgp-trust-manage/).
+- **Generate Revocation Certificate...**: make the file that lets you cancel
+  this key later. Do this now, not when you need it. See
+  [Key Revocation](/advanced/key-revocation/).
+
+### Key servers
+
+- **Search Keyserver...**: look someone up online. Started from a key you have
+  selected, the search is already filled in for you.
+- **Publish Key to Keyserver...**: upload your public key so others can find
+  it.
+- **Refresh Selected from Keyserver**: fetch the latest copy of a key, in case
+  the owner has changed or revoked it.
+
+See [Key Server Operations](/guides/key-server-operations/) for what these do
+in full.
+
+## Work on Several Keys at Once
+
+<Steps>
+
+1. Tick the box beside each key you want.
+
+2. Open the **Bulk** menu.
+
+3. Pick what to do:
+
+   - **Set Owner Trust for Checked Keys...**: give them all the same trust
+     level.
+   - **Extend Expiry of Checked Keys...**: push back the expiry date on all of
+     them at once. Useful once a year, when several keys come due together.
+   - **Back Up All Private Keys...**: save every private key you have into one
+     file. The best way to make a full backup.
+
+</Steps>
+
+:::note[What "checked" means]
+
+Ticking a box and clicking a row are two different things.
+
+Actions that say **Checked** work on the ticked boxes. If you have not ticked
+anything, they fall back to whatever row you have clicked.
+
+:::
+
+## When an Action Is Greyed Out
+
+If a menu item is greyed out, hover over it. The tooltip says why.
+
+The usual reasons are simple:
+
+- **"Select a key first."** Nothing is selected.
+- **"Select exactly one key for this."** The action only makes sense on one key
+  at a time.
+- **"Only available for a key you own the private half of."** You cannot change
+  someone else's key.
+- **"This key carries no email address."** Nothing to copy.
+- **"Certifying is for vouching for someone else's key."** You do not need to
+  certify your own.
+
+Actions your OpenPGP engine cannot do at all are hidden rather than greyed out,
+so a short menu usually means you are on the rPGP engine. See
+[Multi-Key Database](/advanced/key-database/).