docs(add-portal): specify credential handling for portals needing an API token (#304)

* docs(add-portal): specify credential handling for portals needing an API token

/add-portal can already scaffold a skill for a portal that returns usable
content only through a paid fetching service, but the spec says nothing
about the credential such a skill needs: no guidance on where it lives, no
requirement to document it, no defined failure mode when it is unset, and
no point at which the user learns the portal costs money per query.

Three additions, all to the generator spec:

- Step 2 gains a reconnaissance point for whether the portal needs a
  credential at all, to be raised with the user before scaffolding. A
  portal that bills per query is a different proposition from a free one
  and the user should get to decline it.
- The portal-skill contract gains a Credentials rule: environment variable
  only, named <SERVICE>_API_TOKEN, never a CLI flag (flags leak into shell
  history and process listings), never in url-reference.md or a fixture,
  and a MISSING_CREDENTIALS exit rather than a fallthrough to an
  unauthenticated request that fails confusingly.
- SKILL.md for such a skill must carry a Setup section naming the service,
  the variable, and the per-call billing.

Spec only. All six shipped portals are free and unauthenticated, so no
existing skill changes and the zero-dependency default is untouched.

Evidence this is not speculative: running /add-portal against portals that
sit behind bot-detection produced four token-requiring skills in my own
fork (Bright Data Web Unlocker), each of which had to invent its own
convention for reading, documenting, and failing on the token, because the
spec defines none.

Verified: lint_skills, check_framework_version, security_guards all OK;
python3 -m unittest discover -s tests 196 passed.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* docs(add-portal): subordinate the credential check to the robots.txt decision

Review catch: as written, Step 2.5 could be read as "robots.txt or the
terms said no, but a paid unlocker gets through, so here is the convention
for that" - which would let a paid fetcher launder a robots refusal.

That is not the intent and it contradicts the posture settled in #277/#286
(09-web-research.md, tools/robots_check.py): robots.txt is decided first
and honestly, and is never overridden by better fetching machinery.

State the subordination explicitly in 2.5 rather than leaving it implied by
step order, and record it in the changelog entry so the constraint survives
later edits to the step. The credential path is for portals whose robots.txt
permits access but whose bot protection blocks ordinary fetches - paying for
access a site allows, never paying past a site's no.

Wording follows the reviewer's suggestion.

Verified: lint_skills, check_framework_version, security_guards all OK;
python3 -m unittest discover -s tests 219 passed.

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

CHANGELOG.md

@@ -113,6 +113,19 @@ per-file diff commands.
 
 ### Changed
 
+- **`/add-portal` now specifies how a generated skill handles an API token** - the command
+  could already scaffold a skill for a portal reachable only through a paid fetching
+  service, but said nothing about the credential such a skill needs. It now checks for that
+  case during reconnaissance and raises the per-call cost with the user *before*
+  scaffolding. That check is explicitly subordinate to the `robots.txt`/terms decision
+  in Step 2.4 - a paid fetching service never launders a refusal, and the credential
+  path exists only for portals whose `robots.txt` permits access but whose bot
+  protection blocks ordinary fetches. The portal-skill contract requires the token to come from a
+  `<SERVICE>_API_TOKEN` environment variable (never a CLI flag, never a fixture) and to
+  fail with `MISSING_CREDENTIALS` when unset; and such a skill's `SKILL.md` must carry a
+  Setup section naming the service, the variable, and the billing. Spec only - no shipped
+  portal needs a credential, so no existing skill changes.
+
 - **The four Danish demo portals now ship disabled** (#288) - `jobindex-search`,
   `jobbank-search`, `jobdanmark-search`, and `jobnet-search` default to `enabled: false`,
   and `/setup`'s job-portals question now acts on the answer: it flips them to