style: comment consistency sweep across the crate (#20)

## Summary

Follow-up style pass deferred from PR #19's `dda3ff5`, which only
cleaned up comments added that round. This PR extends the cleanup to the
rest of `crates/oxide-code/src/`, closing four drift classes identified
by a fresh survey. Pure style / docs; `cargo test` passes with the same
733 count before and after, and `cargo llvm-cov` stays at 93.08% line /
92.57% region.

- **Drop design-attribution references to `claude-code`** (`bd932d2`) —
rewrites comments like "matches Claude Code's `prependUserContext()`"
into rationale that stands on its own (cache-invalidation behavior,
API-shape requirements). Wire-compat literals
(`CLAUDE_CODE_BETA_HEADER`, identity prefix, `x-claude-code-session-id`
header, Keychain service name, billing salt) and user-facing CLI prose
in `config` / `config::oauth` stay verbatim — those aren't attribution,
they're interop identifiers or the user's mental model.
- **Add module-level `//!` preambles across the crate** (`0c2a03a`) —
lifts coverage from 8 of 50 `.rs` files to 25 of 50. All ten top-level
module roots (`agent`, `client`, `config`, `main`, `message`, `prompt`,
`session`, `tool`, `tui`, `util`) plus seven heavyweight submodules
(`client/anthropic`, `config/oauth`, `session/{manager, store, entry}`,
`tui/app`, `tui/markdown/render` — all the ~1.5K+ line files) now open
with a noun-phrase role statement. Trivial / name-self-describing
submodules (per-tool files, TUI style helpers, `util/env`, `util/lock`,
etc.) intentionally left uncommented.
- **Unify first-line doc-comment voice to third-person indicative**
(`b8886b9`) — the crate was ~50/50 between imperative (`Build a foo.`)
and third-person indicative (`Builds a foo.`). Stdlib is consistently
third-person, and the existing `//!` preambles already follow it; this
commit aligns every free-function, method, and associated-function first
line. CLI `--help` strings (clap `#[arg(...)]`) stay imperative — that's
the `man`-page convention and mixing voices in a single help output
would read worse than diverging from the rest of the crate.
- **Trim narrate-the-what residue** (`3b74af8`) — two targeted fixes:
`ToolOutput::with_title` doc now explains fluent-construction rationale
instead of restating the method signature, and
`prompt::instructions::load`'s discovery-locations list gets a missing
terminal period on item 1.

The re-survey also revealed that the original plan over-scoped two drift
classes: numbered-list formatting was already canonical on all four
sites after PR #19 (only the one missing period remained), and
narrate-the-what was not a class-wide issue (two real cases, not a
sweep). First-line voice was missing from the original plan entirely and
ended up the largest class.

## Changes

| Area | Files | Notes |
| ---- | ----- | ----- |
| Attribution rewrites | `client/anthropic.rs`, `prompt.rs`,
`prompt/environment.rs` | 10 design-attribution sites rephrased as cache
/ API-shape rationale; +25 / −25 |
| Module preambles | 17 files (10 top-level roots + 7 heavyweight
submodules) | +137 / 0, all additive `//!` blocks |
| Voice unification | 27 files across `client`, `config`, `message`,
`prompt`, `session`, `tool`, `tui`, `util` | +119 / −119 mechanical;
verb takes `-s` suffix on first-line summaries |
| Narrate-the-what | `tool.rs`, `prompt/instructions.rs` | 2 targeted
fixes |

## Test plan

- [x] `cargo fmt --all --check`
- [x] `cargo clippy --all-targets -- -D warnings` — zero warnings
- [x] `cargo test` — 733 pass (unchanged from `main`)
- [x] `cargo llvm-cov --ignore-filename-regex 'main\.rs'` — 93.08% line
/ 93.65% function / 92.57% region (unchanged from `main`)
- [x] `pnpm lint` — 0 errors across 16 files
- [x] `pnpm spellcheck` — 0 errors across 72 files; `.cspell/words.txt`
unchanged
- [ ] GitHub Actions: `rust-check`, `coverage`, `node-check` all green
on this PR

Author: hakula139

crates/oxide-code/src/agent.rs

@@ -1,3 +1,10 @@
+//! Agent turn loop.
+//!
+//! Drives one user → assistant round: streams the model response,
+//! dispatches any tool calls it emits, records each turn to the
+//! session, and stops when the model returns text only or the safety
+//! cap [`MAX_TOOL_ROUNDS`] trips.
+
 pub(crate) mod event;
 
 use anyhow::{Context, Result, bail};

crates/oxide-code/src/client.rs

@@ -1,2 +1,4 @@
+//! Anthropic Messages API client.
+
 pub mod anthropic;
 mod billing;

crates/oxide-code/src/client/anthropic.rs

@@ -1,3 +1,18 @@
+//! Anthropic Messages API streaming client.
+//!
+//! [`Client::stream_message`] drives the main agent loop: assembles
+//! the request (identity prefix, billing attestation for OAuth,
+//! static / dynamic system-block split for cache reuse), POSTs
+//! `/v1/messages` with SSE streaming, and forwards parsed
+//! [`StreamEvent`]s on an mpsc channel. [`Client::complete`] covers
+//! non-streaming one-shots (title generation today, future
+//! classifiers) with optional JSON-schema-constrained output.
+//!
+//! Per-request `anthropic-beta` headers are computed from the model's
+//! [`crate::model::Capabilities`] via [`compute_betas`], so gateways
+//! that reject unsupported betas (Haiku, subscriptions without 1M)
+//! don't 400 on spurious feature flags.
+
 use std::time::Duration;
 
 use anyhow::{Context, Result, bail};
@@ -50,8 +65,7 @@ struct CreateMessageRequest<'a> {
     #[serde(skip_serializing_if = "Option::is_none")]
     thinking: Option<&'a ThinkingConfig>,
     /// JSON-schema-constrained output format for one-shot utility calls
-    /// (title generation, future classifiers). Mirrors claude-code's
-    /// `extraBodyParams.output_config`. Must travel alongside the
+    /// (title generation, future classifiers). Must travel alongside the
     /// `structured-outputs-2025-12-15` beta header; both are gated on
     /// `Capabilities::structured_outputs` so unsupported models silently
     /// drop back to free-form text rather than 400ing the gateway.
@@ -77,7 +91,7 @@ pub(crate) struct OutputFormat {
 }
 
 impl OutputFormat {
-    /// Build a `json_schema` output format from a precomputed schema
+    /// Builds a `json_schema` output format from a precomputed schema
     /// value. The schema must already match Anthropic's expectations
     /// (`type: "object"`, `additionalProperties: false`, explicit
     /// `required` array) — we don't validate here.
@@ -89,7 +103,7 @@ impl OutputFormat {
     }
 }
 
-/// Request metadata matching Claude Code's `getAPIMetadata()` format.
+/// Top-level `metadata` object on every outbound request.
 ///
 /// `user_id` is a stringified JSON object containing `session_id` (and
 /// optionally `device_id` / `account_uuid`). The API receives it as a
@@ -354,13 +368,14 @@ impl Client {
 
     /// Stream a message response from the Anthropic API.
     ///
-    /// `system_sections` are the static system prompt sections (one text
-    /// block per section, matching Claude Code's multi-block layout).
+    /// `system_sections` are the static system prompt sections, each
+    /// shipped as its own `system` text block so `cache_control` can
+    /// apply to the static prefix only.
     ///
     /// `user_context` is a `<system-reminder>`-wrapped string that gets
-    /// prepended to the messages array as a synthetic user message,
-    /// matching Claude Code's `prependUserContext()` pattern. This keeps
-    /// dynamic content (CLAUDE.md) out of the `system` parameter.
+    /// prepended to the messages array as a synthetic user message, so
+    /// dynamic content (CLAUDE.md) stays out of the `system` parameter
+    /// and doesn't invalidate the static cache.
     ///
     /// Returns a channel receiver yielding [`StreamEvent`]s. The caller
     /// should recv events as they arrive for real-time output.
@@ -393,7 +408,7 @@ impl Client {
             None
         };
 
-        // Build system blocks matching Claude Code's `splitSysPromptPrefix`:
+        // Assemble the system-block array:
         //   1. Billing header (no cache_control)
         //   2. Identity prefix (no cache_control)
         //   3. Static sections joined (cache_control: ephemeral, scope: global)
@@ -469,7 +484,7 @@ impl Client {
         Ok(rx)
     }
 
-    /// Send a single non-streaming completion request and return the
+    /// Sends a single non-streaming completion request and returns the
     /// concatenated text of the assistant's response.
     ///
     /// Used for background helpers like AI title generation — a one-shot
@@ -533,7 +548,7 @@ impl Client {
         Ok(join_text_blocks(content))
     }
 
-    /// Build the `metadata.user_id` field as a stringified JSON object.
+    /// Builds the `metadata.user_id` field as a stringified JSON object.
     fn build_metadata(&self) -> RequestMetadata {
         build_metadata(&self.session_id)
     }
@@ -547,7 +562,7 @@ fn build_metadata(session_id: &str) -> RequestMetadata {
     RequestMetadata { user_id }
 }
 
-/// Compute the `anthropic-beta` header value for a request targeting
+/// Computes the `anthropic-beta` header value for a request targeting
 /// `model`. Each beta is gated on a specific `Capabilities` flag from
 /// the [`crate::model`] lookup table, so adding or bumping a model only
 /// means editing that one table — this function stays fixed.
@@ -644,7 +659,7 @@ pub(crate) fn supports_structured_outputs(model: &str) -> bool {
     crate::model::lookup(model).is_some_and(|info| info.capabilities.structured_outputs)
 }
 
-/// Strip the `[1m]` tag (if any) from a caller-supplied model string,
+/// Strips the `[1m]` tag (if any) from a caller-supplied model string,
 /// returning the canonical API model ID. The tag is a client-side
 /// convention — the Anthropic API rejects it on the wire.
 ///
@@ -677,7 +692,7 @@ fn tag_offset(model: &str) -> Option<usize> {
     model.to_lowercase().find("[1m]")
 }
 
-/// Serialize the JSON request body for [`Client::complete`]. Extracted
+/// Serializes the JSON request body for [`Client::complete`]. Extracted
 /// so the billing-header / identity-prefix / system-block assembly can
 /// be asserted on without a live HTTP client; the HTTP leg of
 /// [`Client::complete`] is covered behind a wiremock harness (see
@@ -753,7 +768,7 @@ fn build_completion_body(
     Ok(body)
 }
 
-/// Flatten a `messages.create` response's content array into the
+/// Flattens a `messages.create` response's content array into the
 /// assistant's user-visible text. Extracted so the filter logic is
 /// reusable and independently testable.
 fn join_text_blocks(content: Vec<ContentBlock>) -> String {
@@ -774,7 +789,7 @@ struct CompletionResponse {
     content: Vec<ContentBlock>,
 }
 
-/// Map `std::env::consts::OS` to the Stainless SDK's `normalizePlatform` names.
+/// Maps `std::env::consts::OS` to the Stainless SDK's `normalizePlatform` names.
 fn normalize_platform(os: &str) -> &'static str {
     match os {
         "macos" => "MacOS",
@@ -788,7 +803,7 @@ fn normalize_platform(os: &str) -> &'static str {
     }
 }
 
-/// Map `std::env::consts::ARCH` to the Stainless SDK's `normalizeArch` names.
+/// Maps `std::env::consts::ARCH` to the Stainless SDK's `normalizeArch` names.
 fn normalize_arch(arch: &str) -> &'static str {
     match arch {
         "x86" => "x32",
@@ -799,7 +814,7 @@ fn normalize_arch(arch: &str) -> &'static str {
     }
 }
 
-/// Split system sections at the boundary marker into static and dynamic parts.
+/// Splits system sections at the boundary marker into static and dynamic parts.
 ///
 /// Returns `(static_sections, dynamic_sections)`. The boundary marker itself
 /// is excluded from both. Sections before the boundary are static (globally
@@ -828,7 +843,7 @@ fn split_at_boundary<'a>(sections: &[&'a str]) -> (Vec<&'a str>, Vec<&'a str>) {
     }
 }
 
-/// Extract the text of the first user message for fingerprint computation.
+/// Extracts the text of the first user message for fingerprint computation.
 fn first_user_text(messages: &[Message]) -> &str {
     messages
         .iter()
@@ -911,7 +926,7 @@ async fn stream_sse(
     Ok(())
 }
 
-/// Parse a single SSE frame into a [`StreamEvent`].
+/// Parses a single SSE frame into a [`StreamEvent`].
 ///
 /// Per the SSE spec, multiple `data:` lines concatenate with `\n`.
 /// Anthropic currently emits single-line data, but we follow the spec
@@ -1266,10 +1281,10 @@ mod tests {
 
     #[test]
     fn build_metadata_wraps_session_id_in_stringified_json() {
-        // The API accepts `metadata.user_id` as a string, not a nested
-        // object — claude-code stringifies a JSON object with `session_id`
-        // (and sometimes `device_id` / `account_uuid`). Round-trip check
-        // keeps the contract explicit.
+        // `metadata.user_id` is a stringified JSON object on the wire
+        // (contains `session_id` and optionally `device_id` /
+        // `account_uuid`), not a nested object. Round-trip check keeps
+        // the double-encoding explicit.
         let meta = build_metadata("abc-123");
         let parsed: serde_json::Value = serde_json::from_str(&meta.user_id).unwrap();
         assert_eq!(parsed["session_id"], "abc-123");
@@ -1338,9 +1353,9 @@ mod tests {
 
     #[test]
     fn build_completion_body_oauth_injects_billing_header_and_cch() {
-        // OAuth must emit an initial billing block (Claude Code's fingerprint
-        // contract) and the placeholder `cch=00000` must be replaced by an
-        // actual 5-hex-digit tag via `inject_cch`.
+        // OAuth must emit an initial billing block carrying the version
+        // fingerprint, and the placeholder `cch=00000` must be replaced
+        // by an actual 5-hex-digit tag via `inject_cch`.
         let body = build_completion_body(
             "claude-haiku-4-5",
             "sys-prompt",

crates/oxide-code/src/client/billing.rs

@@ -15,7 +15,7 @@ const CCH_PLACEHOLDER: &str = "cch=00000";
 
 // ── Public API ──
 
-/// Compute the 3-character hex fingerprint suffix for `cc_version`.
+/// Computes the 3-character hex fingerprint suffix for `cc_version`.
 ///
 /// `SHA-256(salt + chars_at_indices + version)`, take first 3 hex chars.
 /// Character extraction uses Unicode scalar indexing, which matches
@@ -31,7 +31,7 @@ pub(super) fn compute_fingerprint(first_user_message: &str, version: &str) -> St
     format!("{:02x}{:02x}", hash[0], hash[1])[..3].to_string()
 }
 
-/// Build the billing attribution header with a `cch=00000` placeholder.
+/// Builds the billing attribution header with a `cch=00000` placeholder.
 ///
 /// The placeholder is later replaced by [`inject_cch`] with the computed hash.
 pub(super) fn build_billing_header(version: &str, fingerprint: &str) -> String {
@@ -43,7 +43,7 @@ pub(super) fn build_billing_header(version: &str, fingerprint: &str) -> String {
     )
 }
 
-/// Compute xxHash64 of the request body and replace the `cch` placeholder.
+/// Computes xxHash64 of the request body and replaces the `cch` placeholder.
 ///
 /// The hash is computed over the body *with* the placeholder in place,
 /// then the placeholder is replaced with the 5-char hex result. Only the

crates/oxide-code/src/config.rs

@@ -1,3 +1,10 @@
+//! Configuration loading.
+//!
+//! Layered precedence (highest wins): env vars > project `ox.toml` >
+//! user `~/.config/ox/config.toml` > built-in defaults. Auth follows
+//! the same precedence but terminates at the first source that
+//! resolves (API key env > API key in file > OAuth credentials).
+
 mod file;
 mod oauth;
 
@@ -36,7 +43,7 @@ pub struct Config {
 }
 
 impl Config {
-    /// Load configuration from files and environment variables.
+    /// Loads configuration from files and environment variables.
     ///
     /// Precedence (highest wins): env vars > project `ox.toml` > user
     /// `~/.config/ox/config.toml` > built-in defaults.

crates/oxide-code/src/config/file.rs

@@ -51,7 +51,7 @@ pub(super) struct TuiConfig {
 // ── Merge ──
 
 impl FileConfig {
-    /// Merge two configs. Fields in `other` take precedence over `self`.
+    /// Merges two configs. Fields in `other` take precedence over `self`.
     fn merge(self, other: Self) -> Self {
         Self {
             client: merge_section(self.client, other.client, ClientConfig::merge),
@@ -83,7 +83,7 @@ impl TuiConfig {
     }
 }
 
-/// Merge two optional config sections. When both are present, merge their
+/// Merges two optional config sections. When both are present, merges their
 /// fields. When only one is present, use it as-is.
 fn merge_section<T>(base: Option<T>, other: Option<T>, merge: fn(T, T) -> T) -> Option<T> {
     match (base, other) {
@@ -94,7 +94,7 @@ fn merge_section<T>(base: Option<T>, other: Option<T>, merge: fn(T, T) -> T) ->
 
 // ── Loading ──
 
-/// Load and merge configuration from user and project TOML files.
+/// Loads and merges configuration from user and project TOML files.
 ///
 /// Precedence (highest wins): project config > user config.
 /// Environment variable overrides are applied later in [`super::Config::load`].
@@ -136,12 +136,12 @@ fn user_config_path() -> Option<PathBuf> {
     )
 }
 
-/// Walk from CWD upward to find the nearest `ox.toml`.
+/// Walks from CWD upward to find the nearest `ox.toml`.
 fn find_project_config() -> Option<PathBuf> {
     find_project_config_from(std::env::current_dir().ok()?)
 }
 
-/// Walk from `start` upward to find the nearest `ox.toml`.
+/// Walks from `start` upward to find the nearest `ox.toml`.
 ///
 /// Separated from [`find_project_config`] for testability (avoids changing
 /// the process CWD).

crates/oxide-code/src/config/oauth.rs

@@ -1,3 +1,13 @@
+//! Claude Code OAuth credentials.
+//!
+//! Loads the OAuth access token from the macOS Keychain (service
+//! `"Claude Code-credentials"`) and `~/.claude/.credentials.json`,
+//! preferring whichever has the later expiry. Refreshes via the
+//! Anthropic token endpoint when the access token is expired or about
+//! to expire, writing the new pair back to both sources. A directory-
+//! based advisory lock keeps two `ox` instances from refreshing
+//! concurrently and clobbering each other's tokens.
+
 use std::path::{Path, PathBuf};
 use std::time::Duration;
 
@@ -54,7 +64,7 @@ impl OAuthCredential {
 
 // ── Token Loading ──
 
-/// Load an OAuth access token from Claude Code credentials, refreshing
+/// Loads an OAuth access token from Claude Code credentials, refreshing
 /// proactively if the token is within 5 minutes of expiry.
 pub async fn load_token() -> Result<String> {
     let file_path = credentials_path().context("could not determine home directory")?;
@@ -105,7 +115,7 @@ pub async fn load_token() -> Result<String> {
     }
 }
 
-/// Load credentials, preferring the macOS Keychain over the file.
+/// Loads credentials, preferring the macOS Keychain over the file.
 ///
 /// File contents are user-writable, so an attacker with write access to
 /// `~/.claude/.credentials.json` could otherwise spoof a far-future expiry
@@ -243,7 +253,7 @@ struct RefreshResponse {
     scope: Option<String>,
 }
 
-/// Write refreshed tokens back to the credentials file (and macOS Keychain),
+/// Writes refreshed tokens back to the credentials file (and macOS Keychain),
 /// preserving unknown fields.
 ///
 /// Replaces the file atomically (temp + rename) so a crash mid-write cannot
@@ -283,7 +293,7 @@ fn write_refreshed_credentials(path: &Path, response: &RefreshResponse) -> Resul
     Ok(())
 }
 
-/// Write `bytes` to `path` atomically with owner-only (`0o600`) permissions
+/// Writes `bytes` to `path` atomically with owner-only (`0o600`) permissions
 /// on Unix. Creates a sibling `.tmp.<uuid>` file then renames — the rename
 /// is atomic on POSIX, so readers always see either the old or new content.
 fn atomic_write_private(path: &Path, bytes: &[u8]) -> Result<()> {

crates/oxide-code/src/main.rs

@@ -1,3 +1,10 @@
+//! Binary entry point.
+//!
+//! Parses CLI flags, loads [`Config`], resolves which session to
+//! resume (if any), and dispatches into one of three run modes: TUI
+//! (default), bare REPL (`--no-tui`), or headless one-shot (`-p`).
+//! Signal handling and session summary writes on abort live here.
+
 mod agent;
 mod client;
 mod config;
@@ -142,7 +149,7 @@ async fn async_main() -> Result<()> {
 
 // ── Session Helpers ──
 
-/// Print a table of recent sessions and exit. With `all = true`, spans
+/// Prints a table of recent sessions and exits. With `all = true`, spans
 /// every project; otherwise scoped to the current working directory.
 fn list_sessions(all: bool) -> Result<()> {
     let store = SessionStore::open()?;
@@ -157,7 +164,7 @@ fn list_sessions(all: bool) -> Result<()> {
     )
 }
 
-/// Detect the terminal width for title truncation in `--list`.
+/// Detects the terminal width for title truncation in `--list`.
 /// Returns `None` when stdout is not a TTY (piped / redirected) or
 /// when the window size cannot be queried — the renderer skips
 /// truncation in either case so downstream tools see the full title.
@@ -181,7 +188,7 @@ fn create_tool_registry() -> ToolRegistry {
     ])
 }
 
-/// Wait for any shutdown signal — SIGINT (portable), SIGTERM, or
+/// Waits for any shutdown signal — SIGINT (portable), SIGTERM, or
 /// SIGHUP (Unix only). Returns when the first signal arrives.
 ///
 /// Installs the handlers lazily on first call. Callers that embed this