docs(auth): CLI auth docs and gated e2e conformance test

[Bccorb]

Summary

Final issue in the CLI auth epic (#38). Documents the authenticated CLI and adds an end-to-end test that exercises the login and token lifecycle against a running instance.

Docs

A new README section, "Authenticating against an instance", covers every command added across #39 to #46 with runnable examples:

• Profiles (profile add/list/use/remove, --profile, SEAMLESS_PROFILE)
• Login (email OTP)
• whoami, logout, logout --all
• sessions list and revoke
• config get/set/roles/diff/apply (config as code)
• users and org admin verbs
• Token storage and the OS keychain, per platform (macOS Keychain, Windows Credential Manager, Linux Secret Service)
• The headless SEAMLESS_REFRESH_TOKEN fallback for CI

End-to-end test

src/core/authFlow.e2e.test.ts drives the CLI's real modules (completeLogin, createAuthClient, keychain, refresh) against a running instance. It is skipped unless SEAMLESS_E2E_URL is set, so it never runs in the normal unit suite (verified: npm test shows it skipped).

It covers the acceptance criteria:

• Registers and verifies a user, then logs in through the real email OTP flow and holds a session that authenticates (GET /users/me).
• Transparent refresh: with a stale access token, the client refreshes on 401 and rotates the refresh token.
• Reuse handling: a reused refresh token is rejected (401) after rotation.
• Rate limit: an opt-in test (second flag SEAMLESS_E2E_RATE_LIMIT) exhausts the OTP limiter and asserts the 429 path, kept out of routine runs because it saturates the shared per-IP limiter for 15 minutes.

To read the OTP the CLI generates, the test wraps fetch to add the instance's external-delivery header to the CLI's own generate call and captures the returned code, so login is a single deterministic generate rather than a racing second one. The external-delivery seam only returns codes outside production, so the target instance must run in dev/test and have email_otp enabled.

Run it with:

SEAMLESS_E2E_URL=http://localhost:5312 npm test
# include the rate-limit test (exhausts the OTP limiter for ~15 min):
SEAMLESS_E2E_URL=http://localhost:5312 SEAMLESS_E2E_RATE_LIMIT=1 npm test

Verification

• npm run build (tsc strict): passing.
• npm test: 81 passing, 4 e2e skipped (no SEAMLESS_E2E_URL).
• The auth contract used by the test (register, generate with external delivery, verify, login, refresh) is confirmed against the auth-api source, and the Node 24 Dockerfile fix (Conformance (seamless verify) fails: auth-api container runs Node 20 but the package requires Node >=24 #50) has landed so the conformance stack can host the instance.

Acceptance criteria

• Docs cover every new command with examples.
• Tests cover login, refresh rotation, and rate-limit handling.

Closes #47

[Bccorb]

Live verification: ran the non-destructive subset against a local instance (Node 24 auth-api + postgres) with SEAMLESS_E2E_URL=http://localhost:5312:

✓ src/core/authFlow.e2e.test.ts (4 tests | 1 skipped) 946ms
  ✓ holds a session that authenticates against the instance
  ✓ refreshes transparently when the access token is stale
  ✓ rejects a reused refresh token
  ↓ surfaces the OTP rate limiter as a 429 (skipped; needs SEAMLESS_E2E_RATE_LIMIT)

Test Files  1 passed (1)
Tests  3 passed | 1 skipped (4)

So a full email OTP login through the real completeLogin flow, an authenticated GET /users/me, transparent refresh with token rotation, and refresh-reuse rejection all pass end to end against a running instance. The 429 test is verified by construction and gated because it saturates the shared per-IP OTP limiter for 15 minutes.