diff --git a/.gitea/workflows/scripts/install-caller-skills.sh b/.gitea/workflows/scripts/install-caller-skills.sh
index ea3b4ba..84ba3a4 100644
--- a/.gitea/workflows/scripts/install-caller-skills.sh
+++ b/.gitea/workflows/scripts/install-caller-skills.sh
@@ -18,6 +18,12 @@
 # Required env (provided by the workflow step): NAME WORKSPACE SECRETS_JSON
 #   (SECRETS_JSON = toJSON(secrets); passed so a caller's setup.sh can read repo-specific secrets
 #    whose names this framework cannot know in advance.)
+#
+# IMPORTANT — caller-skill secrets read from SECRETS_JSON MUST be single-line. The runner masks a
+# secret's value in logs by exact match, but toJSON(secrets) escapes newlines to '\n', so a MULTILINE
+# secret (e.g. a raw PEM key) no longer matches the mask and would print in cleartext in the step's
+# "expression evaluated to …" log line. Store multiline values base64-encoded (single-line) and
+# decode them inside setup.sh. Single-line values mask correctly.
 set -eu
 
 DIR="${WORKSPACE:-$GITHUB_WORKSPACE}/.gitea/agent-skills"