diff --git a/lib/auth/server.ts b/lib/auth/server.ts
index 0520fc7..559982b 100644
--- a/lib/auth/server.ts
+++ b/lib/auth/server.ts
@@ -10,9 +10,14 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const successHtml = fs.readFileSync(path.join(__dirname, "..", "oauth-success.html"), "utf-8");
 
 /**
- * Start a small local HTTP server that waits for /auth/callback and returns the code
- * @param options - OAuth state for validation
- * @returns Promise that resolves to server info
+ * Start a local HTTP listener that captures the OAuth authorization code from /auth/callback.
+ *
+ * @param options - Configuration object.
+ * @param options.state - Expected `state` query parameter value used to validate the callback.
+ * @returns An object containing:
+ *  - `port`: the bound port number (1455),
+ *  - `close()`: a function that closes the server,
+ *  - `waitForCode(expectedState?)`: a function that waits up to ~60 seconds for an authorization code; returns `{ code: string }` when a code is captured (and matches the configured state), or `null` if no code is received within the timeout.
  */
 export function startLocalOAuthServer({ state }: { state: string }): Promise<OAuthServerInfo> {
 	const server = http.createServer((req, res) => {
@@ -77,4 +82,4 @@ export function startLocalOAuthServer({ state }: { state: string }): Promise<OAu
 				});
 			});
 	});
-}
+}
\ No newline at end of file
diff --git a/lib/logger.ts b/lib/logger.ts
index 2d23da0..478834f 100644
--- a/lib/logger.ts
+++ b/lib/logger.ts
@@ -143,6 +143,18 @@ function emit(level: LogLevel, message: string, extra?: Record<string, unknown>)
 	logToConsole(level, message, sanitizedExtra);
 }
 
+/**
+ * Sends a user-facing notification (toast) through the configured logger client, if available.
+ *
+ * Constructs a payload with a title derived from the log level, the provided message as the body,
+ * and optional extra metadata, then attempts to call `app.notify` or `app.toast`. If no app or
+ * compatible send method is present, the function returns without action. Failures to send are
+ * recorded as a warning via console logging.
+ *
+ * @param level - The severity level for the notification (`"debug" | "info" | "warn" | "error"`). A value of `"error"` produces an "error" title; other values produce a "warning" title.
+ * @param message - The primary text to show in the notification body.
+ * @param extra - Optional metadata to include with the notification payload.
+ */
 function notifyToast(level: LogLevel, message: string, extra?: Record<string, unknown>): void {
 	const app = (loggerClient as any)?.app;
 	if (!app) return;
@@ -165,6 +177,15 @@ function notifyToast(level: LogLevel, message: string, extra?: Record<string, un
 	});
 }
 
+/**
+ * Writes a plugin-prefixed log message to the console when the log level is applicable.
+ *
+ * Logs warnings and errors unconditionally; debug and info messages are written only when console logging is enabled. The message is prefixed with the plugin name and, if provided, `extra` is JSON-stringified and appended; on JSON serialization failure, `String(extra)` is appended instead.
+ *
+ * @param level - Log level determining severity and console method
+ * @param message - Primary log message text
+ * @param extra - Additional context appended to the message; values are JSON-stringified when possible
+ */
 function logToConsole(level: LogLevel, message: string, extra?: Record<string, unknown>): void {
 	const isWarnOrError = level === "warn" || level === "error";
 	const shouldLogDebugOrInfo = CONSOLE_LOGGING_ENABLED && (level === "debug" || level === "info");
@@ -360,4 +381,4 @@ function toErrorMessage(error: unknown): string {
 		return error.message;
 	}
 	return String(error);
-}
+}
\ No newline at end of file
diff --git a/lib/request/fetch-helpers.ts b/lib/request/fetch-helpers.ts
index 677e365..f49650c 100644
--- a/lib/request/fetch-helpers.ts
+++ b/lib/request/fetch-helpers.ts
@@ -248,9 +248,10 @@ export function createCodexHeaders(
 }
 
 /**
- * Handles error responses from the Codex API
- * @param response - Error response from API
- * @returns Response with error details
+ * Enriches a Codex API error Response with structured error details and rate-limit metadata.
+ *
+ * @param response - The original error Response from a Codex API request
+ * @returns A Response with the same status and statusText whose body is either the original raw body or a JSON object containing an `error` object with `message`, optional `friendly_message`, optional `rate_limits`, and `status`. When the body is enriched, the response `Content-Type` is set to `application/json; charset=utf-8`.
  */
 export async function handleErrorResponse(response: Response): Promise<Response> {
 	const raw = await response.text();
@@ -368,4 +369,4 @@ function toInt(v: string | null): number | undefined {
 	if (v == null) return undefined;
 	const n = parseInt(v, 10);
 	return Number.isFinite(n) ? n : undefined;
-}
+}
\ No newline at end of file