docs: implementation plan for PKCE + device authorization login (programmatic auth)

[zajca]

What

Detailed implementation plan for adding browser-based login to kbagent: PKCE authorization-code flow (default, same-machine) and device authorization flow (RFC 8628 semantics; fallback + --device-code), issuing Keboola programmatic session credentials (kbc_at_* access token + kbc_rt_* refresh token) used against Storage/Manage APIs as Authorization: Bearer + X-KBC-ProjectId.

Static Storage-token auth remains fully supported and unchanged — both auth modes coexist so existing users and CI never have to change anything.

Document: docs/programmatic-auth-login-plan.md

Key design points

• No config.json schema change: session metadata lives in a new sibling auth.json; session-registered projects use a sentinel token = "kbc-session://{project_id}" in the existing field, so older CLI versions degrade to a clean per-project 401 instead of breaking (no CURRENT_CONFIG_VERSION bump).
• Secrets never in plaintext: access + refresh tokens stored via OS keychain (keyring, new dependency) with a passphrase-encrypted file (AES-256-GCM + scrypt, existing cryptography dep) as fallback — per the RFC's hard requirement, no escape hatch.
• Zero-churn bearer wiring: httpx.Auth-based BearerAuth + per-stack SessionTokenProvider (thread- and cross-process-safe refresh rotation with a dedicated flock; leverages the server's 30 s refresh grace window), injected via the existing client-factory default in services/base.py — no changes at the ~150 factory call sites.
• New command group: kbagent auth login [--device-code] [--register-projects], auth status, auth logout.
• v1 scope: CLI command paths (Storage + Manage). kbagent serve, SDK facade and MCP subprocess keep static tokens and fail fast on session projects (follow-up).
• 6-PR delivery plan, test plan (incl. refresh race tests), docs/plugin-sync checklist, risk register.

Sources

• keboola/connection docs/rfc/programmatic-auth/device-authorization-flow.md (v8)
• keboola/platform-architecture-and-concepts#12 (auth/programmatic-auth.md)

Notes for reviewers

This PR is docs-only (plan review). Feedback wanted especially on: the sentinel-token backward-compat approach, access-token-in-keychain caching decision, and the PR phasing.