docs(claude-code): mark subscription mode broken on macOS

PR #12 shipped oauthToken support with optimistic framing, but testing
revealed @anthropic-ai/claude-agent-sdk has a macOS-specific bug: the
SDK isolates CLAUDE_CONFIG_DIR per invocation and tries to copy
~/.claude/.credentials.json, which doesn't exist on macOS (creds live
in the Keychain). The OAuth token gets misclassified as an API key
and requests are billed against API credits instead of the
subscription — subscribers without API credits see "Credit balance is
too low" errors.

Direct `claude -p` works fine, so the upstream SDK is the broken layer.

Changes:
- README Claude Code section: lead with the macOS status note and
  point subscribers at ClaudeProvider + ANTHROPIC_API_KEY as the
  current workaround.
- JSDoc on ClaudeCodeProvider: same status note.
- billing_error message: explain the bug and recommend the workaround
  so users can self-diagnose from the error alone.

No code removal — when the SDK fix lands upstream, oauthToken users
will Just Work without any code changes here.

src/providers/claude-code.ts

@@ -2,17 +2,27 @@
  * Claude Code Provider
  *
  * Wraps `@anthropic-ai/claude-agent-sdk` so consumers can use a local
- * Claude Code installation — including Claude Pro/Max subscription
- * accounts authenticated via `claude login` — through the same
- * BaseAIProvider interface as the other providers.
+ * Claude Code installation through the same BaseAIProvider interface
+ * as the other providers.
  *
- * Tradeoffs vs the direct Anthropic API provider:
- * - Authenticates via the local CLI, so subscription users (no API key)
- *   can use it.
- * - Requires `claude` to be installed and logged in on the host.
- * - Higher latency (shells out to a CLI process per request).
+ * Status:
+ * - apiKey mode: works reliably.
+ * - oauthToken (subscription) mode: currently broken on macOS due to an
+ *   upstream SDK bug. The SDK isolates CLAUDE_CONFIG_DIR per invocation
+ *   and tries to copy ~/.claude/.credentials.json, which doesn't exist on
+ *   macOS (creds live in the Keychain). The OAuth token gets misclassified
+ *   as an API key by the SDK, so requests are billed against API credits
+ *   instead of the subscription. Subscribers without API credits will see
+ *   "Credit balance is too low" errors. The oauthToken field is wired up
+ *   and will work as expected once the SDK fix lands upstream.
+ *
+ * Other tradeoffs:
+ * - Requires `claude` CLI installed on the host.
+ * - Higher latency (spawns a CLI process per request).
  * - Designed for agent workflows, but used here in single-turn mode
  *   (maxTurns: 1, no tools) for plain text completion.
+ * - If you have an API key, prefer the direct ClaudeProvider for simpler,
+ *   lower-latency access.
  *
  * @see https://docs.anthropic.com/claude/docs/claude-code-sdk
  */
@@ -362,7 +372,7 @@ export class ClaudeCodeProvider extends BaseAIProvider {
       },
       billing_error: {
         type: AIErrorType.AUTHENTICATION,
-        message: 'Billing error. For Claude Pro/Max subscribers using the SDK: run `claude setup-token` and pass the resulting token as `oauthToken` (interactive `claude login` alone is not sufficient for non-interactive SDK calls).'
+        message: 'Billing error from Claude Code SDK. If you are a Pro/Max subscriber on macOS, this is likely the upstream @anthropic-ai/claude-agent-sdk Keychain bug — the SDK misclassifies the OAuth token as an API key. Workaround: use ClaudeProvider directly with an ANTHROPIC_API_KEY instead.'
       },
       rate_limit: {
         type: AIErrorType.RATE_LIMIT,