chore: update GPG signing instructions for devcontainer setup and troubleshooting

.devcontainer/README.md

@@ -117,6 +117,14 @@ On Windows PowerShell, use:
 The helper auto-selects `gpg2`/`gpg` based on where your key is visible, which
 avoids host setups where the two binaries use different keyrings.
 
+If you rotate keys, run the helper again on the host before the next rebuild so
+the container can import the new public key.
+
+Expected behavior after rebuild:
+
+- Signing keeps working when host forwarding/import and `.git/signing.pub` are in sync.
+- If signing breaks after rebuild (especially after key rotation), regenerate `.git/signing.pub` with the helper and rebuild again.
+
 After **Rebuild Container** (or next container start), verify in the container:
 
 ```bash
@@ -124,57 +132,26 @@ gpg --list-secret-keys --keyid-format=long
 git commit -S -m "test signed commit"
 ```
 
-### Manually importing your public key
-
-If `git commit -S` fails with `gpg: signing failed: No secret key`, the forwarded
-agent holds your **private** key but the container keyring is missing the matching
-**public** key, so gpg can't locate it. Import it manually.
-
-First, on the **host**, find your real key ID. On macOS, gpg is often `gpg2` and
-may use a different keyring than plain `gpg`, so use the binary that actually holds
-your keys:
-
-```bash
-gpg2 --list-secret-keys --keyid-format=long   # ID is the part after the '/' on the sec line
-git config --global user.signingkey           # what git is set to sign with
-```
-
-Export that key on the **host** into the shared repo checkout (`.git/` is not
-tracked, so it is a safe drop point):
-
-```bash
-# on the HOST — replace with your real key ID
-gpg2 --armor --export <YOUR_KEY_ID> \
-  > /Users/<you>/path/to/alfresco-ng2-components/.git/signing.pub
-```
-
-Import it in the **container** and point git at it:
-
-```bash
-# in the CONTAINER (repo root)
-gpg --import .git/signing.pub && rm .git/signing.pub
-git config --global user.signingkey <YOUR_KEY_ID>
-
-# verify — a passphrase prompt (if any) appears on the HOST, not the container
-gpg --list-secret-keys --keyid-format=long
-echo test | gpg -u <YOUR_KEY_ID> --clearsign
-git commit -S -m "test signed commit"
-```
-
 ### Other signing gotchas
 
 - `gpg-connect-agent 'keyinfo --list' /bye` printing **`connection to agent is in
   restricted mode`** is **normal and good** — VS Code forwards the host's restricted
   `gpg-agent.extra` socket, which allows signing but blocks key listing. It does not
   mean the agent is missing.
-- Still failing after importing the public key? The forwarding didn't attach —
-  on the host run `gpgconf --launch gpg-agent` and confirm `echo test | gpg2
-  --clearsign` works there, then **Dev Containers: Rebuild Container**.
+- If signing fails after a rebuild, regenerate `.git/signing.pub` on the host with
+  `./.devcontainer/export-signing-key.sh` (or
+  `./.devcontainer/export-signing-key.ps1` on PowerShell) and rebuild again.
+- If it still fails, the forwarding likely did not attach — on the host run
+  `gpgconf --launch gpg-agent` and confirm `echo test | gpg2 --clearsign` works,
+  then **Dev Containers: Rebuild Container**.
 - Confirm `gnupg2` is present in the container: `gpg --version`.
 - The automatic gitconfig / GPG / SSH forwarding is a feature of the **VS Code
   Dev Containers extension**. If you run this config via the plain
   `@devcontainers/cli`, you must mount `~/.gnupg`, `~/.gitconfig`, and the agent
   sockets yourself.
 
+For a full troubleshooting checklist, see
+[docs/dev-containers.md](../docs/dev-containers.md#signing-gpgpgp-troubleshooting).
+
 See [docs/dev-containers.md](../docs/dev-containers.md#git-operations-and-signing)
 for alternative signing strategies (host-only signing, CI-enforced signing).