content: write HardenedPass reference and landing pages

Every setting, the security model, troubleshooting and the landing page,
in both languages. Also adds the Firefox save prompt tip and full menu
paths on the sync and autofill pages. Still drafts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

1 files changed, 72 insertions, 4 deletions

diff --git a/content/en/hardenedpass/reference/troubleshooting/index.md b/content/en/hardenedpass/reference/troubleshooting/index.md
index 4221c83..3dfce92 100644
--- a/content/en/hardenedpass/reference/troubleshooting/index.md
+++ b/content/en/hardenedpass/reference/troubleshooting/index.md
@@ -1,13 +1,81 @@
 +++
 title = "Troubleshooting"
 date = 2026-11-05T00:00:00Z
-description = ""
+description = "Common HardenedPass errors, what they mean and how to fix them: passphrase, keys, SSH, push rejected, detached head, autofill."
 weight = 110
 draft = true
 +++
 
-Placeholder.
+## Keys and passphrases
 
-## First heading
+**The app asks for the passphrase again and says it is wrong.** The passphrase does not
+match the private key. If you changed the key's passphrase on a computer, the app
+needs the new one. If caching is on, it asks again and replaces the old value.
 
-Text.
+**`Failed to import PGP key`.** The file is not a key the app can use. Keys without an
+encryption subkey are rejected, because they could not decrypt anything. Check that you
+exported the **private** key, with `gpg --armor --export-secret-keys`.
+
+**An entry will not open and no key matches.** The store is encrypted for a key that is
+not imported. Compare **Store recipients** on the import screen, or the `.gpg-id` file,
+with the keys in **Key manager**. A public key alone cannot decrypt: import the private
+one.
+
+**The key is on a smartcard.** GnuPG exports a stub for such a key, with no secret
+material in it. The app cannot decrypt with that. It needs the real private key.
+
+**`Found .gpg-id, but it contains an invalid key ID, fingerprint or user ID`.** The
+`.gpg-id` file has something the app does not understand. Check it on a computer: one
+key ID, fingerprint or address per line.
+
+## Connecting
+
+**`The provided repository URL is not valid`.** See the address forms in
+[Connect the app]({{< relref "/hardenedpass/getting-started/connect" >}}).
+
+**`Wrong password` or `Wrong passphrase`.** For a repository password or an SSH key's
+passphrase. Many hosting services want an access token rather than the account password.
+
+**`Selected file does not appear to be an SSH private key`.** You picked the public key,
+or a file in another format. Choose the file without `.pub`.
+
+**The sync fails after the server was reinstalled or moved.** Its host key changed. If
+you are sure why, use **Clear saved host key** on the repository screen, under **Edit
+Git server settings**. If you are not, treat it as an attack until you know better.
+
+**SSH login is refused.** Check that the public key is on the server, for the right
+account. **View generated public SSH key** shows it for a key made on the phone.
+
+## Syncing
+
+**`Push was rejected by remote, run pull before pushing again`.** The server has commits
+you do not have. Use **Synchronize repository**, which pulls and then pushes.
+
+**`Pull has failed, you're in a detached head`.** A conflict stopped the rebase.
+[Sync]({{< relref "/hardenedpass/using/sync" >}}) has the steps.
+
+**`Merge has failed, you're in a conflicting state`.** The same conflict, with **Rebase
+on pull** off. The way out is the hard reset in
+[Sync]({{< relref "/hardenedpass/using/sync" >}}), after saving anything you need.
+
+**`The repository must be cloned before syncing changes`.** The store on the phone has no
+remote. Set one under **Edit Git server settings** and clone it.
+
+## Autofill
+
+**No suggestions appear.** Check that HardenedPass is the selected autofill service in
+Android's settings, and that the browser is on the list in
+[Autofill]({{< relref "/hardenedpass/using/autofill" >}}).
+
+**Only the password gets filled.** That is the browser's support level, as with Vanadium.
+
+**`This app is currently not supported`.** The app cannot save from there. You can still
+add the entry by hand.
+
+**Nothing happens after tapping Save.** Android 14 and later hold back background
+windows, and the app has a workaround: update to the latest version.
+
+## Still stuck?
+
+Open an issue on the [tracker](https://github.com/danixland/HardenedPass/issues). Say
+which version you run and what you did. Never paste passwords, keys or real entry names.