diff --git a/.github/actions/autofix-prepare/action.yml b/.github/actions/autofix-prepare/action.yml
index b6627aa3..3371d707 100644
--- a/.github/actions/autofix-prepare/action.yml
+++ b/.github/actions/autofix-prepare/action.yml
@@ -102,6 +102,10 @@ runs:
         PROJECT_ID: ${{ inputs.project_id }}
       run: |
         set -euo pipefail
+        if [ -z "$PROJECT_ID" ]; then
+          echo "::error::project_id is empty. It is normally read from an Actions variable: check that TRACEWAY_PROJECT_ID exists as a variable and not only as a secret, because a job calling a reusable workflow cannot read the secrets context from its with: block."
+          exit 1
+        fi
         printf '%s' "$TOKEN" | traceway login --url "$URL" --token-stdin
         traceway projects use "$PROJECT_ID"
 
diff --git a/.github/workflows/autofix.yml b/.github/workflows/autofix.yml
index 63e68856..d4e64296 100644
--- a/.github/workflows/autofix.yml
+++ b/.github/workflows/autofix.yml
@@ -9,14 +9,19 @@
 # token; every write (push, PR, comment, archive) happens in the publish step
 # from validated inputs. That split is the security model, not the agent's
 # tool allowlist.
-name: Traceway auto-fix
+name: Traceway auto-fix (reusable)
 
 on:
   workflow_call:
     inputs:
       issue_number:
+        # Deliberately a string. A caller composing this from
+        # github.event.issue.number and a workflow_dispatch input yields a
+        # string on dispatch, and a number-typed input rejects that during
+        # workflow validation, before any job exists — so the run reports only
+        # "a workflow file issue" with no logs and no annotation.
         description: Number of the issue the Traceway GitHub channel opened
-        type: number
+        type: string
         required: true
       allowed_authors:
         description: Comma-separated GitHub logins allowed to trigger a run (the owner of the channel's token); every other issue author is refused
diff --git a/docs/pages/learn/auto-fix.mdx b/docs/pages/learn/auto-fix.mdx
index 4a04a099..e63da744 100644
--- a/docs/pages/learn/auto-fix.mdx
+++ b/docs/pages/learn/auto-fix.mdx
@@ -32,7 +32,7 @@ The reusable workflow composes the three steps, with Claude Code as the tested a
 
 1. **Create two Traceway bot users** (or one; see [Credentials](#credentials)) and mint a [personal access token](/learn/cli-auth#personal-access-tokens) for each.
 2. **Add repository secrets**: `TRACEWAY_TOKEN` (read-only), `TRACEWAY_PUBLISH_TOKEN` (write, optional: without it the exception is never archived), `GH_PUSH_TOKEN` (a GitHub token that can push branches, open pull requests and comment; the built-in `github.token` cannot open a pull request that triggers other workflows), and `ANTHROPIC_API_KEY`.
-3. **Add a repository variable** `TRACEWAY_PROJECT_ID` with the project's id (`traceway projects list`).
+3. **Add a repository variable** `TRACEWAY_PROJECT_ID` with the project's id (`traceway projects list`). It has to be a variable rather than a secret, and the two fail differently: `with:` cannot reference the `secrets` context at all, so a caller that tries is rejected during workflow validation with no job and no logs, while an undefined `vars.TRACEWAY_PROJECT_ID` quietly resolves to an empty string and the prepare step stops with an error naming this variable.
 4. **Point the GitHub channel at the repository** with a label such as `traceway`, and create the caller workflow:
 
 ```yaml