Missing repository secret produces "provide a valid GitHub personal token", which points debugging at scopes rather than at the absent secret

[mursalfk]

Description

When the referenced secret does not exist, GitHub substitutes an empty string
rather than failing the step, so the action receives token: "". The resulting
error is:

You must provide a valid GitHub personal token to gather your metrics

That message reads as "your token is wrong" — invalid, expired, or missing a
scope — so the natural response is to regenerate the PAT and re-check scopes.
The actual cause is that no secret with that name exists in the repository, or
it was added under Dependabot or Codespaces rather than Actions,
which is easy to do since those are adjacent tabs on the same settings page.

Reproduction

1. Add a workflow using lowlighter/metrics@latest with
   token: ${{ secrets.METRICS_TOKEN }}
2. Do not create METRICS_TOKEN, or create it under the Dependabot tab
3. Run the workflow

Expected

The empty case distinguished from the invalid case. Something like:

No token was provided: `token` resolved to an empty string.

This usually means the referenced secret does not exist. Check that it is
set under Settings > Secrets and variables > Actions (not Dependabot or
Codespaces), and that the name matches the workflow exactly.

Why this is worth separating

The two failures have completely different fixes, and the current message only
describes one of them. Empty input is trivially detectable before any API call
is attempted — if (!token) throw new Error(...) distinguishes it from a token
that is present but rejected by the API.

Environment

• Action: lowlighter/metrics@latest
• Runner: ubuntu-latest
• Plugins: isocalendar, languages, habits

Related

The setup documentation covers creating a PAT and its scopes thoroughly, but
does not flag the three-tab secrets page as a place people land wrong. A note
there would help even without the code change.

I am happy to open a PR adding the empty-token guard if you would like it.