#2902 Docs: account requirement and auth gate (swamp-club#2231)

Docs for the auth gate (swamp-club#2231), needed before it launches. From this release, every swamp subcommand needs a swamp-club.com account. Design reference: design/surfaces/auth-gate.md in the swamp repo.

Behaviour the docs must cover

• Account required. Every subcommand needs a credential: swamp auth login, or a collective key via SWAMP_API_KEY, SWAMP_API_KEY_FILE or --club-api-key-file.

• Exempt. These work without an account:

  • bare swamp, --help/-h and --version/-V;
  • swamp auth login, swamp auth logout and swamp auth whoami;
  • swamp help [command...], swamp completions <shell>, swamp version and swamp update.

  Everything else is gated, including init, serve, worker and doctor. update stays available so a blocked user can install a fixing release, including after a signing-key rotation.

• Signed proof, offline use. auth login (and any whoami) caches a signed proof (~/.config/swamp/auth_verified.json), valid for 14 days. While it is valid, swamp runs with no network call and keeps working through a swamp-club outage. It is refreshed in the background once it is more than 7 days old.

• Blocks.

  • A revoked key always blocks.
  • Without a valid proof, swamp must reach swamp-club once.
  • An unreachable swamp-club, a 429, or a 403 from a proxy or firewall blocks.
  • A 5xx from swamp-club fails open for at most 24 hours.

• Error messages. There is one for each case: no account, revoked, not verified in N days, could not reach swamp-club, refused (rate limited or blocked), and unverified for over 24 hours. JSON mode returns code auth_gate_blocked, plus a reason object (kind: no_credential, revoked, refused, unreachable_unverified or unverified_for_a_day, with status, retryAfterSeconds or daysSinceVerification where they apply) and temporary. Temporary blocks (refused, unreachable, swamp-club failing for a day) exit 75 so CI can retry them; a missing or revoked credential exits 1.

• CI. Set both SWAMP_API_KEY and SWAMP_SIGNIN_TOKEN. The signin token is shown once when the collective token is created, on the swamp-club page and by swamp auth token create. It lets CI run while swamp-club is unreachable. It is checked live at most once an hour per key, and a revoked key blocks. Rotating the API key needs a new signin token.

• Daemons. swamp serve daemon enable and swamp worker daemon enable point the service at the enabling user's config dir, so log in as that user first. Worker daemons enabled before this release must be re-enabled. Containers set SWAMP_API_KEY plus SWAMP_SIGNIN_TOKEN.

• Logout. swamp auth logout also clears the cached proof.

• Removed. The "authentication required from October 1st" warning is gone.

Manual pages to update or add (swamp-club content/manual)

• how-to/authenticate-with-api-keys.md: add SWAMP_SIGNIN_TOKEN and CI setup.
• how-to/swamp-serve/run-as-system-daemon.md: daemon credentials, and re-enabling worker daemons.
• how-to/swamp-serve/deploy-on-kubernetes.md, how-to/swamp-serve/deploy-headless-oauth.md, how-to/swamp-serve/run-multi-instance-deployment.md: container credentials, including the signin token.
• tutorials/your-first-automation.md and the other tutorials: add a swamp auth login step before the first command.
• how-to/troubleshoot-your-swamp-repo.md: each block message, its cause and its fix.
• explanation/api-key-scoping.md: how the signin token relates to the API key.
• New explanation page: why swamp requires an account and how offline operation works (signed proof, 14-day expiry, weekly refresh, 24-hour fail-open on swamp-club errors).
• Release notes / upgrade note: the account requirement, CI secrets, and re-enabling worker daemons.