diff --git a/.devcontainer/Dockerfile b/.devcontainer/Dockerfile
index edeb0f9..a3fe744 100644
--- a/.devcontainer/Dockerfile
+++ b/.devcontainer/Dockerfile
@@ -56,12 +56,16 @@ ENV PATH=/home/vscode/.nix-profile/bin:/home/vscode/.npm-global/bin:$PATH
 #                           so those live in flake.nix's devShell, not here.
 #   - nodejs_22           → host for the Claude Code CLI (run as `claude` from
 #                           anywhere, so it stays globally on PATH, not in the shell)
+#   - gh                  → GitHub CLI for PRs/issues/auth; global so it's usable
+#                           from anywhere. Auth is persisted across rebuilds via a
+#                           named volume on ~/.config/gh (see devcontainer.json).
 RUN . /home/vscode/.nix-profile/etc/profile.d/nix.sh \
     && nix registry add nixpkgs github:NixOS/nixpkgs/nixos-25.05 \
     && nix profile install \
         nixpkgs#direnv \
         nixpkgs#nix-direnv \
-        nixpkgs#nodejs_22
+        nixpkgs#nodejs_22 \
+        nixpkgs#gh
 
 # Claude Code CLI — installed to a per-user prefix so root isn't required.
 RUN . /home/vscode/.nix-profile/etc/profile.d/nix.sh \
diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json
index db3d2a8..8dd1c06 100644
--- a/.devcontainer/devcontainer.json
+++ b/.devcontainer/devcontainer.json
@@ -9,13 +9,14 @@
   "init": true,
   "mounts": [
     "source=claude-code-config-${devcontainerId},target=/home/vscode/.claude,type=volume",
+    "source=gh-config-${devcontainerId},target=/home/vscode/.config/gh,type=volume",
     "source=${localEnv:HOME}${localEnv:USERPROFILE}/.gitconfig,target=/home/vscode/.gitconfig,type=bind,readonly"
   ],
   "containerEnv": {
     "CLAUDE_CONFIG_DIR": "/home/vscode/.claude",
     "GIT_CONFIG_GLOBAL": "/home/vscode/.gitconfig.local"
   },
-  "postCreateCommand": "sudo chown -R vscode:vscode /home/vscode/.claude && bash .devcontainer/setup-git.sh && direnv allow /workspace && nix develop /workspace --command bash -c 'uv sync --frozen'",
+  "postCreateCommand": "sudo chown -R vscode:vscode /home/vscode/.claude /home/vscode/.config/gh && bash .devcontainer/setup-git.sh && direnv allow /workspace && nix develop /workspace --command bash -c 'uv sync --frozen'",
   "customizations": {
     "vscode": {
       "extensions": [
diff --git a/CONTRIBUTOR.md b/CONTRIBUTOR.md
new file mode 100644
index 0000000..ce4d40f
--- /dev/null
+++ b/CONTRIBUTOR.md
@@ -0,0 +1,58 @@
+# Contributing to Komet Node
+
+## Development environment
+
+This repository ships a [devcontainer](.devcontainer/) that provisions the full
+toolchain (Nix, the flake's `nix develop` shell, the Claude Code CLI, and the
+GitHub CLI). Open the repo in a devcontainer-aware editor and everything below is
+available out of the box.
+
+## Using the GitHub CLI (`gh`)
+
+`gh` is preinstalled in the devcontainer for creating pull requests, reviewing
+issues, and other GitHub tasks from the terminal.
+
+### Authenticating
+
+Authenticate once with a personal access token:
+
+```bash
+gh auth login
+```
+
+Choose **GitHub.com** → **HTTPS** → **Paste an authentication token** when
+prompted, then paste the token you create below.
+
+Your credentials are stored in `~/.config/gh` inside the container, which is
+backed by a named volume. This means **your token survives container rebuilds** —
+you only need to authenticate once, not every time the container is recreated.
+
+To check or reset your authentication at any time:
+
+```bash
+gh auth status   # show the current login
+gh auth logout   # remove stored credentials
+```
+
+### Creating a token with minimal permissions
+
+Create a **fine-grained** personal access token at **GitHub → Settings → Developer
+settings → [Fine-grained personal access tokens](https://github.com/settings/personal-access-tokens/new)**
+with the least privilege for your work:
+
+- **Repository access** → *Only select repositories* → `runtimeverification/komet-node`
+- **Contents** → *Read and write*
+- **Pull requests** → *Read and write*
+- **Issues** → *Read and write* (only if you triage issues)
+
+`Metadata → Read` is selected automatically; leave everything else at *No access*.
+
+## Signing commits
+
+To sign commits made with `git`, add an SSH or GPG key of type **Signing key** to
+your GitHub account.
+
+> [!WARNING]
+> Never place an SSH key registered as an **Authentication key** in the container.
+> An authentication key grants full account-wide git access and would bypass the
+> minimal permissions of your fine-grained PAT. Use a **signing-only** key here.