docs(context): record the port fallback notice and version reporting

Author: cloudbridgeuy

CLAUDE.md

@@ -29,7 +29,7 @@ This is a Rust workspace with three main components:
 - Core streaming library for LLM interactions
 - Provider-agnostic API that supports multiple LLM services
 - Uses Server-Sent Events (SSE) via a custom eventsource-client fork
-- Providers: OpenAI, Anthropic, Google, Mistral, Ollama, Groq, Jina, DeepSeek
+- Providers: OpenAI, Anthropic, Google, Mistral, Ollama, Groq, Jina, DeepSeek, and ChatGPT (subscription)
 - Simple, synchronous-style API that abstracts away complex async operations
 
 ### CLI (`crates/llm_stream/`)
@@ -38,6 +38,8 @@ This is a Rust workspace with three main components:
 - Features: conversation history, templates, presets, external editor support
 - Syntax highlighting using syntect with Tokyo Night themes
 - Streaming output with spinners and colored terminal output
+- ChatGPT subscription sign-in (`--login`, `--login-status`, `--logout`), stored at `<config_dir>/auth.json` with mode `0600`
+- Reasoning controls for the `chatgpt` provider: `--reasoning-effort`, `--reasoning-summary`, `--models`
 
 ### Build Tools (`xtask/`)
 - Custom build automation following the cargo-xtask pattern
@@ -53,6 +55,19 @@ Each LLM provider has a dedicated module (e.g., `anthropic.rs`, `openai.rs`) tha
 - Streaming delta processing
 - Provider-specific error handling
 
+### The ChatGPT Provider
+Unlike every other provider, `--api chatgpt` authenticates with a ChatGPT subscription's
+OAuth credentials rather than an API key, over an undocumented endpoint internal to
+OpenAI's Codex CLI. Two rules are load-bearing and easy to break by accident:
+
+- **Never send a `version` header** to that endpoint — it gates model access, and any value
+  we send is compared against Codex's own release train. The guard comment lives at
+  `lib/llm_stream/src/chatgpt.rs:337`.
+- **Never print raw access or refresh tokens**, in logs, errors, or debug output.
+
+There is deliberately no local model allowlist: `--model` passes through verbatim and the
+server's own refusal reaches the operator. `--models` probes the server for the answer.
+
 ### Configuration System
 - TOML-based configuration in `~/.config/llm-stream/config.toml`
 - Supports templates for prompt engineering
@@ -71,9 +86,33 @@ Each LLM provider has a dedicated module (e.g., `anthropic.rs`, `openai.rs`) tha
 
 ## Testing
 
-Run tests with appropriate environment variables for API keys:
+```bash
+cargo test                              # aborts at the first failing target — see below
+cargo test -p llm-stream --bin llm-stream   # CLI unit tests
+cargo test -p llm_stream --lib              # library unit tests
+cargo test -p llm-stream --test cli         # offline CLI integration tests
+```
+
+`prelude::tests::test_preset_system_over_config_system` is a known, pre-existing failure. It
+makes a bare `cargo test` stop before reaching `crates/llm_stream/tests/`, so name the
+target explicitly.
+
+Some providers' unit tests read API keys from the environment:
+
 ```bash
 OPENAI_API_KEY=sk-... cargo test
 ```
 
+### The live ChatGPT smoke test
+
+`crates/llm_stream/tests/live_chatgpt.rs` performs one real round trip against a ChatGPT
+subscription. It skips unless opted in, because every run spends the operator's quota:
+
+```bash
+LLM_STREAM_LIVE_TEST=1 cargo test -p llm-stream --test live_chatgpt -- --nocapture
+```
+
+It requires a completed `llm-stream --login`. **Never make it unconditional and never wire
+it into CI.**
+
 Examples are available in `lib/llm_stream/examples/` for each provider.

CONTEXT.md

@@ -32,6 +32,11 @@ Running `llm-stream --login` authenticates the operator against a ChatGPT subscr
 - **WHEN** the loopback callback's `state` parameter is missing or does not match the value generated at the start of `--login`
 - **THEN** the sign-in fails and no credentials are stored
 
+#### Scenario: The preferred loopback port is occupied
+- **WHEN** the operator runs `llm-stream --login` while another process holds port 1455
+- **THEN** the CLI prints a warning to stderr naming port 1455, the port it fell back to, and what to close
+- **AND** the sign-in continues on the fallback port
+
 ### Requirement: Credential storage permissions
 Stored ChatGPT credentials are only ever readable and writable by the file's owner.
 
@@ -161,3 +166,10 @@ The config file's top-level `base_url`, `env`, `key`, `version`, and `model` def
 #### Scenario: Config file matches the selected provider
 - **WHEN** the operator runs `llm-stream --api <provider> "<prompt>"` and the config file's top-level `api` matches `<provider>`, or omits `--api` entirely
 - **THEN** `base_url`, `env`, `key`, `version`, and `model` are inherited from the config file as before
+
+### Requirement: Version reporting
+Running `llm-stream --version` identifies the binary and the version actually installed.
+
+#### Scenario: Reporting the installed version
+- **WHEN** the operator runs `llm-stream --version`
+- **THEN** the CLI prints `llm-stream <version>`, where `<version>` is the version of the installed `llm-stream` package