docs(advanced): improve wording and clarity

- improve wording in app-data-storage for clarity and consistency
- rephrase encryption description to say keys derived from name
- clarify tamper detection: altered files are refused
- simplify sentences in app-secure-key and describe key storage
- replace "throw the key away" with "delete the key" for precision
- clarify Maximum secure-level behavior: key rotated weekly
- fix various small wording and grammar issues in advanced docs
- make portable-mode and profiles text clearer about data transfer
- adjust memory-security wording about wiping buffers and limits
- minor rewording in key-database and key-package for clarity
- fix CLI doc: --profile needs folder name; where to find it
- change caution headings to be more descriptive and noticeable

8 files changed, 51 insertions, 48 deletions

diff --git a/src/content/docs/advanced/app-data-storage.md b/src/content/docs/advanced/app-data-storage.md
index 443d804..6408fa9 100644
--- a/src/content/docs/advanced/app-data-storage.md
+++ b/src/content/docs/advanced/app-data-storage.md
@@ -7,10 +7,10 @@ sidebar:
 ---
 
 Besides your keys, GpgFrontend saves a few things of its own: key server
-entries, key generation profiles, window positions, and similar. The sensitive
+entries, key generation profiles, window positions, and so on. The sensitive
 parts are encrypted with the program's own key.
 
-This all happens on its own. There is nothing to set up and nothing to
+All of this happens automatically. There is nothing to set up and nothing to
 maintain. This page is here for people who want to know what is going on.
 
 For the key that does the protecting, and the choices you have about it, see
@@ -18,12 +18,12 @@ For the key that does the protecting, and the choices you have about it, see
 
 ## How It Works
 
-Each saved item is encrypted on its own, with its own key worked out from the
-program's key and that item's name. Nothing is encrypted with one shared key,
-so getting at one item tells an attacker nothing about the others.
+Each saved item is encrypted on its own, with its own key made from the
+program's key and the item's name. Nothing is encrypted with one shared key,
+so breaking into one item tells an attacker nothing about the others.
 
-The encryption is authenticated. If a file is altered, GpgFrontend notices and
-refuses it rather than using bad data.
+The encryption also detects tampering. If someone changes a file, GpgFrontend
+notices and refuses to use it.
 
 Files are written in a way that cannot leave a half-finished result behind. If
 the program or the computer stops in the middle of a write, the old version
@@ -31,8 +31,9 @@ survives intact.
 
 ## Where the Files Are
 
-Inside your profile, in a folder called `data_objs`. Each file is named after a
-scrambled version of what it holds, so the file names give nothing away.
+The files live inside your profile, in a folder called `data_objs`. Each file
+is named after a scrambled version of what it holds, so the file names give
+nothing away.
 
 Each [Secure Level](/advanced/memory-security/) keeps its data apart from the
 others. That is why lowering the level makes data saved at a higher one
diff --git a/src/content/docs/advanced/app-secure-key.md b/src/content/docs/advanced/app-secure-key.md
index 74e44b4..93c7ff8 100644
--- a/src/content/docs/advanced/app-secure-key.md
+++ b/src/content/docs/advanced/app-secure-key.md
@@ -6,9 +6,8 @@ sidebar:
   order: 8
 ---
 
-GpgFrontend keeps one key of its own. It uses it to lock the things the
-program saves for you: settings, cached details, key server entries, and
-similar.
+GpgFrontend keeps one key of its own. This key locks the data the program
+saves for you: settings, cached details, key server entries, and so on.
 
 This is **not** one of your OpenPGP keys. It never touches your messages,
 your files, or your keyring. GpgFrontend makes it for you the first time it
@@ -32,7 +31,8 @@ of your other things anyway.
 
 ### System keychain
 
-GpgFrontend hides its key in the place your computer already keeps passwords:
+GpgFrontend stores its key in the place where your computer already keeps
+passwords:
 
 - **Windows**: Credential Manager
 - **macOS**: your login keychain
@@ -61,8 +61,8 @@ lose data.
 :::caution[A forgotten PIN cannot be recovered]
 
 There is no reset that keeps your data. If you cannot remember the PIN, the
-only way to start the program again is to throw the key away, and everything
-it was protecting becomes unreadable for good.
+only way to start the program again is to delete the key. Everything the key
+was protecting then becomes unreadable forever.
 
 GpgFrontend offers that as **Forgot PIN? Reset** after three wrong tries, and
 warns you twice before doing it.
@@ -87,9 +87,9 @@ find **Secure Level**. It has four settings:
 The first three are about memory, and are explained on
 [Memory Security](/advanced/memory-security/).
 
-**Maximum** is the only one that affects this page. It swaps the key for a
-fresh one every week, so an old copy of your saved data stops being useful
-quickly.
+**Maximum** is the only one that affects this page. It replaces the key with
+a new one every week. So if someone steals an old copy of your saved data, it
+soon becomes useless to them.
 
 :::caution[Turning Maximum back off]
 
@@ -106,9 +106,9 @@ restart for you.
 
 ## Where the Key Is Kept
 
-Inside the profile you are using, in a folder called `secure`. If you use
-several [profiles](/advanced/profiles/), each has its own key, and each can
-have its own protection setting.
+The key lives inside the profile you are using, in a folder called `secure`.
+If you use several [profiles](/advanced/profiles/), each has its own key, and
+each can have its own protection setting.
 
 :::note[Changed in v2.2.2]
 
diff --git a/src/content/docs/advanced/key-database.mdx b/src/content/docs/advanced/key-database.mdx
index cd4801c..a652336 100644
--- a/src/content/docs/advanced/key-database.mdx
+++ b/src/content/docs/advanced/key-database.mdx
@@ -48,7 +48,7 @@ The **first database in the list is the default**. It is the one GpgFrontend
 uses when you start the application. On a normal setup, it points to your GnuPG
 home directory.
 
-You can have up to eight.
+You can have up to eight databases.
 
 ## Add a New Key Database
 
@@ -67,8 +67,8 @@ You can have up to eight.
 
    - **Automatic**: GpgFrontend picks a safe place to keep it. Just give it a
      name and you are done. Use this unless you have a reason not to.
-   - **Manual**: you pick the folder yourself. For people setting up something
-     specific, such as pointing at an existing GnuPG home directory.
+   - **Manual**: you pick the folder yourself. Use this only for special
+     setups, such as pointing at an existing GnuPG home directory.
 
 </Steps>
 
@@ -218,10 +218,10 @@ When you open the profile on the other computer, GpgFrontend tells you which
 databases were left behind. Each one shows as **Inactive** in the Key Databases
 settings until you edit it and point it at a folder on the new computer.
 
-:::caution[Nothing warns you loudly at export time]
+:::caution[This is easy to miss when you export]
 
-The export window mentions this in small grey text under **What goes in**. It
-is easy to miss.
+The export window only mentions this in small grey text under **What goes
+in**, so it is easy to overlook.
 
 If you want your keys to travel with the profile, check that the database is in
 **Automatic** mode, or that the folder you picked in **Manual** mode sits
diff --git a/src/content/docs/advanced/key-package.mdx b/src/content/docs/advanced/key-package.mdx
index bb9519c..12817e3 100644
--- a/src/content/docs/advanced/key-package.mdx
+++ b/src/content/docs/advanced/key-package.mdx
@@ -21,8 +21,8 @@ GpgFrontend can save two kinds of file, and they are easy to mix up:
 - A **profile file** (`.gfp`) carries a **whole setup**: keys, settings and
   saved state together. See [Profiles](/advanced/profiles/).
 
-If you want your new computer to look and behave exactly like the old one, you
-want a profile file. If you only want your keys, you want a KeyPackage.
+If you want your new computer to look and behave exactly like the old one,
+use a profile file. If you only want your keys, use a KeyPackage.
 
 :::
 
diff --git a/src/content/docs/advanced/memory-security.md b/src/content/docs/advanced/memory-security.md
index 8b20168..68e706e 100644
--- a/src/content/docs/advanced/memory-security.md
+++ b/src/content/docs/advanced/memory-security.md
@@ -43,8 +43,8 @@ Choose this if you want the best speed and the fewest surprises.
 
 ### Enhanced (1)
 
-Everything sensitive goes into buffers that are wiped clean when they are
-allocated and wiped again when they are released.
+Everything sensitive goes into memory buffers that are wiped clean before use
+and wiped again after use.
 
 This costs almost nothing and is a sensible step up.
 
@@ -57,7 +57,7 @@ so it does not end up on your disk by accident.
 GpgFrontend also clears the text box and its undo history before encrypting or
 decrypting, so your plain text cannot be brought back with Ctrl+Z.
 
-This is the strongest memory protection, and what to pick if you are handling
+This is the strongest memory protection. Pick it if you are handling
 something sensitive.
 
 ### Maximum (3)
@@ -86,5 +86,5 @@ GpgFrontend keeps your secrets in memory for as short a time as it can, avoids
 making extra copies, and wipes what it can before letting memory go.
 
 It cannot protect you from someone who already controls your computer. If
-malware is running as you, or someone has your unlocked machine, no memory
-setting saves you.
+malware is running under your account, or someone is sitting at your unlocked
+computer, no memory setting can save you.
diff --git a/src/content/docs/advanced/module-controller.md b/src/content/docs/advanced/module-controller.md
index 8d8a73f..093b9d6 100644
--- a/src/content/docs/advanced/module-controller.md
+++ b/src/content/docs/advanced/module-controller.md
@@ -40,7 +40,8 @@ Start**.
 
 :::caution[Some features disappear with their module]
 
-Turning off a module removes what it does. Switch off the key server module,
+Turning off a module removes the features it provides. Switch off the key
+server module,
 for example, and the **Key Servers** page vanishes from Settings, along with
 key server search and publishing.
 
diff --git a/src/content/docs/advanced/portable-mode.md b/src/content/docs/advanced/portable-mode.md
index 8736cf7..fb07fb5 100644
--- a/src/content/docs/advanced/portable-mode.md
+++ b/src/content/docs/advanced/portable-mode.md
@@ -27,7 +27,7 @@ for each system:
 - **Portable**: everything stays in the program's own folder.
 
 Pick the portable one and unpack it wherever you want it, such as onto a USB
-drive. That is all there is to it.
+drive. That is all you need to do.
 
 :::note[Changed in v2.2.2]
 
@@ -39,9 +39,9 @@ If you were using one, download the portable build instead.
 
 :::caution[The two do not share anything]
 
-An installed copy and a portable copy keep completely separate data. Moving
-from one to the other looks like starting from scratch. Your keys are not
-carried over on their own.
+An installed copy and a portable copy keep completely separate data. If you
+move from one to the other, you start with empty settings and no keys.
+Nothing is carried over on its own.
 
 To bring a setup across, see [Profiles](/advanced/profiles/). You can save your
 whole setup to one file and open it in the other copy.
@@ -63,7 +63,7 @@ A portable copy cannot use your computer's password store to protect its own
 key. That store belongs to one computer, and a portable copy has to work on
 any computer you plug it into.
 
-That option is greyed out for you, so there is nothing to do. See
+That option is greyed out for you, so there is nothing you need to do. See
 [Application Secure Key](/advanced/app-secure-key/) if you want the details.
 
 ## Tip: Moving Between Computers
diff --git a/src/content/docs/advanced/profiles.mdx b/src/content/docs/advanced/profiles.mdx
index 8b07a53..cffc317 100644
--- a/src/content/docs/advanced/profiles.mdx
+++ b/src/content/docs/advanced/profiles.mdx
@@ -69,7 +69,7 @@ Everything to do with profiles sits in the **Profiles** menu in the menu bar:
 
 - **Manage Profiles**: see every profile on this computer, and open or remove
   one.
-- **Open Recent**: jump back to a profile you used lately.
+- **Open Recent**: jump back to a profile you used recently.
 - **New Profile**: start a fresh, empty setup on this computer.
 - **Open Profile File**: work inside a profile file without copying it onto
   this computer.
@@ -137,9 +137,9 @@ in one file you can copy anywhere.
 
 <Aside type="caution" title="The file holds your keys">
 
-Keep the passphrase on. Without it, anyone who gets the file can read your
-keys and everything else in the profile, and can change it before you open
-it.
+Keep the passphrase protection turned on. Without it, anyone who gets the
+file can read your keys and everything else in the profile, and can change it
+before you open it.
 
 There is no way to recover the passphrase if you forget it. Write it down
 somewhere safe.
@@ -159,8 +159,9 @@ elsewhere, such as your system GnuPG home directory. That happens when you
 chose **Manual** mode for the database, or when you told the profile to use the
 keys you already had.
 
-Such a database is still named in the file, but it arrives empty on the other
-computer, and shows as **Inactive** until you point it at a folder there.
+That kind of database is still listed in the file, but it arrives empty on
+the other computer, and shows as **Inactive** until you point it at a folder
+there.
 
 <Aside type="tip" title="Check before you rely on it">
 
@@ -224,8 +225,8 @@ gpgfrontend --profile a3f19c
 gpgfrontend ~/Documents/work.gfp
 ```
 
-`--profile` wants the profile's **folder name**, not the name you gave it. You
-can see the folder in **Manage Profiles**.
+`--profile` needs the profile's **folder name**, not the name you gave it.
+You can see the folder name in **Manage Profiles**.
 
 If you name a profile that does not exist, the program stops and says so. It
 does not create one for you.