chore: install gnupg2 for GPG agent forwarding and update devcontainer configuration

.devcontainer/Dockerfile

@@ -9,8 +9,9 @@ ENV PNPM_HOME=/home/node/.local/share/pnpm
 ENV PATH=${PNPM_HOME}:${PATH}
 
 # Install Chromium for Karma/ChromeHeadless test execution inside the container.
+# gnupg2 is required so VS Code can forward the host gpg-agent for signed commits.
 RUN apt-get update \
-    && apt-get install -y --no-install-recommends chromium \
+    && apt-get install -y --no-install-recommends chromium gnupg2 \
     && rm -rf /var/lib/apt/lists/*
 
 # Configure Corepack-managed pnpm globally at image build time.

.devcontainer/README.md

@@ -0,0 +1,79 @@
+# Dev Container
+
+Quick start for developing `alfresco-ng2-components` inside the VS Code Dev Container.
+For the full guide (Nx targets, daemon, troubleshooting, base-image updates) see
+[docs/dev-containers.md](../docs/dev-containers.md).
+
+## Prerequisites
+
+- Docker Desktop running
+- VS Code with the **Dev Containers** extension (`ms-vscode-remote.remote-containers`)
+
+## Getting Started
+
+1. Open the repository in VS Code.
+2. Run **Dev Containers: Reopen in Container** from the Command Palette (or accept the prompt).
+3. Wait for the post-create step (`pnpm install --frozen-lockfile`) to finish.
+4. Use the integrated terminal as usual, e.g. `pn nx test core`.
+
+Rebuild (**Dev Containers: Rebuild Container**) after changing
+[`Dockerfile`](./Dockerfile) or [`devcontainer.json`](./devcontainer.json).
+
+## What's Included
+
+- Node base image (digest-pinned) with Corepack-activated **pnpm**
+- **Chromium** for Karma / `ChromeHeadless` tests (`CHROME_BIN` is preset)
+- **GitHub CLI** (`gh`) via the `github-cli` dev container feature
+- **gnupg2** so the host `gpg-agent` can be forwarded for signed commits
+- Persistent pnpm store volume and warm Nx daemon (`NX_DAEMON=true`)
+
+## GitHub CLI
+
+`gh` is preinstalled. Authenticate once per container:
+
+```bash
+gh auth login
+```
+
+Or export a token instead: `export GH_TOKEN=<your-token>`.
+
+## Signed Commits With Host Credentials
+
+The VS Code Dev Containers extension handles this automatically — your private
+keys never enter the container, only the agent socket is forwarded:
+
+- Your host **`.gitconfig`** (including `user.signingkey` and `commit.gpgsign`)
+  is copied into the container.
+- Your host **`gpg-agent`** is forwarded (this is why `gnupg2` is installed), and
+  your GPG **public** keys are imported into the container.
+- Your host **SSH agent** is forwarded, so `git push` over SSH uses your host keys.
+
+### One-time host setup
+
+Make sure signing is configured on the **host** (this is what gets copied in):
+
+```bash
+git config --global user.signingkey <YOUR_KEY_ID>
+git config --global commit.gpgsign true
+```
+
+Then, inside the container, verify the key is visible before committing:
+
+```bash
+gpg --list-secret-keys
+git commit -S -m "your message"   # -S optional if commit.gpgsign is true
+git push
+```
+
+### If signing fails
+
+- Getting `error: gpg failed to sign the data` / `no secret key`? The agent
+  forwarding didn't attach — **Rebuild Container** or reload the VS Code window.
+- Confirm `gnupg2` is present: `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.
+
+See [docs/dev-containers.md](../docs/dev-containers.md#git-operations-and-signing)
+for alternative signing strategies (host-only signing, CI-enforced signing).

.devcontainer/devcontainer-lock.json

@@ -0,0 +1,9 @@
+{
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {
+      "version": "1.1.0",
+      "resolved": "ghcr.io/devcontainers/features/github-cli@sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671",
+      "integrity": "sha256:d22f50b70ed75339b4eed1ba9ecde3a1791f90e88d37936517e3bace0bbad671"
+    }
+  }
+}

.devcontainer/devcontainer.json

@@ -12,7 +12,9 @@
   },
 
   // Features to add to the dev container. More info: https://containers.dev/features.
-  // "features": {},
+  "features": {
+    "ghcr.io/devcontainers/features/github-cli:1": {}
+  },
 
   "remoteUser": "node",
   "containerUser": "node",

docs/dev-containers.md

@@ -50,33 +50,53 @@ When running Nx commands, VS Code may show a notification about a port being ope
 
 ## Git Operations and Signing
 
-You can use Git inside the container, outside the container, or split responsibilities for better key safety.
+The container is set up so you can do all Git work — including signed commits and
+pushes — inside it, using your host credentials and settings. Your private keys
+never enter the container: only the agent socket is forwarded.
 
-Recommended secure default:
+### Option A: Commit and Sign in Container (Recommended)
 
-1. Build, test, and edit code inside the container.
-2. Create signed commits outside the container on the host machine.
+The VS Code Dev Containers extension wires this up automatically:
 
-This reduces exposure of signing keys to container processes while keeping day-to-day development reproducible.
+- Your host `.gitconfig` (including `user.signingkey` and `commit.gpgsign`) is
+  copied into the container.
+- Your host `gpg-agent` is forwarded (this is why `gnupg2` is installed in the
+  image), and your GPG public keys are imported into the container.
+- Your host SSH agent is forwarded, so `git push` over SSH uses your host keys.
 
-### Option A: Sign Commits on Host (Recommended)
+One-time host setup (this is what gets copied in):
+
+```bash
+git config --global user.signingkey <YOUR_KEY_ID>
+git config --global commit.gpgsign true
+```
+
+Then work entirely inside the container:
+
+```bash
+gpg --list-secret-keys            # verify the forwarded key is visible
+git commit -S -m "your message"   # -S optional when commit.gpgsign is true
+git push
+```
+
+If signing fails with `gpg failed to sign the data` / `no secret key`, the agent
+forwarding did not attach — rebuild the container or reload the VS Code window.
+
+> Note: the automatic gitconfig / GPG / SSH forwarding is a feature of the VS Code
+> Dev Containers extension. If you run this configuration via the plain
+> `@devcontainers/cli`, mount `~/.gnupg`, `~/.gitconfig`, and the agent sockets
+> yourself, or fall back to Option B.
+
+### Option B: Sign Commits on Host
+
+For the strongest key isolation, keep signing on the host:
 
 - Keep private signing keys only on the host.
 - Do normal development in the container.
-- Stage and commit from a host terminal in the same repository checkout.
-- Run signed commit commands on host (for example, `git commit -S ...`).
+- Stage and commit from a host terminal in the same repository checkout
+  (for example, `git commit -S ...`).
 
-Good fit when your policy requires strong key isolation.
-
-### Option B: Commit and Sign in Container (With Care)
-
-If your team prefers full in-container Git operations, use one of these approaches:
-
-- Forward SSH agent into the container and use SSH signing.
-- Forward GPG agent/socket into the container instead of copying private keys.
-- Avoid storing raw private keys directly in container filesystems.
-
-This keeps workflows convenient, but still requires careful host and container trust settings.
+Good fit when your policy forbids forwarding signing agents into containers.
 
 ### Option C: Unsigned Commits in Container, Signed Merge in CI/Host
 
@@ -88,8 +108,8 @@ This can simplify local setup for contributors while preserving integrity checks
 ### Practical Daily Pattern
 
 1. Code, lint, and test in the container.
-2. Review and commit on host with signing enabled.
-3. Push from host (or container) based on your credential policy.
+2. Commit and sign in the container using the forwarded host keys.
+3. Push from the container (SSH agent or `gh` credentials are forwarded).
 4. Keep branch protection checks active (status checks, review, signature policy if used).
 
 ## Updating Base Image Safely