diff --git a/docs/forgejo.md b/docs/forgejo.md
index fe93c3d..5f05ffa 100644
--- a/docs/forgejo.md
+++ b/docs/forgejo.md
@@ -414,6 +414,17 @@ Unit tests assume GitHub context by default. When running on a Forgejo runner, s
 
 If `curl -fsSL https://bun.sh/install | bash` fails on your runner, pre-install Bun on the runner image or use the `path_to_bun_executable` input to point to a custom Bun binary.
 
+### Claude Code CLI on Alpine/musl runners
+
+On musl-based runners (Alpine Linux), the native Claude Code binary may fail with `posix_getdents: symbol not found` or similar musl incompatibility errors. This happens because the native binary is built against a newer musl than what stable Alpine releases ship (the required `posix_getdents` is only available in Alpine edge's musl 1.2.5-r21+).
+
+The action detects musl automatically and falls back to `npm install -g @anthropic-ai/claude-code`, which runs on Node.js and avoids native binary issues entirely. This requires Node.js and npm on the runner — if your runner image is based on `node:alpine`, both are already available. No action needed on your part.
+
+If you use a minimal Alpine image without Node.js, either:
+
+- Use a `node:alpine` base image for your runner
+- Pre-install Claude Code and use the `path_to_claude_code_executable` input
+
 ### Claude's tracking comment doesn't appear as a review reply
 
 On Forgejo, review comment triggers (`pull_request_review_comment`) always create a regular issue comment — not a reply in the review thread. This is because Forgejo's webhook payload lacks the top-level `comment` object needed to create a review reply. The response still appears on the PR, just as a standalone comment.