freshcontext-mcp 0.3.19 → 0.3.21

package/dist/core/types.d.ts

@@ -0,0 +1,239 @@
+export interface FreshContext {
+    content: string;
+    source_url: string;
+    content_date: string | null;
+    retrieved_at: string;
+    freshness_confidence: "high" | "medium" | "low";
+    freshness_score: number | null;
+    adapter: string;
+}
+export interface ExtractOptions {
+    url: string;
+    prompt?: string;
+    maxLength?: number;
+    location?: string;
+    remoteOnly?: boolean;
+    maxAgeDays?: number;
+    keywords?: string[];
+}
+export interface AdapterResult {
+    raw: string;
+    content_date: string | null;
+    freshness_confidence: "high" | "medium" | "low";
+}
+export interface EnvelopeFormatOptions {
+    unknownDateText?: string;
+    publishedLabel?: string;
+}
+export type SignalConfidence = "high" | "medium" | "low";
+export type SignalDateConfidence = SignalConfidence | "unknown";
+export type SignalContractVersion = "freshcontext.signal.v1";
+export type SourceAuthorityHint = "high" | "medium" | "low";
+export type SourceDatePolicy = "strict" | "balanced" | "lenient";
+export type SourceFailurePolicy = "exclude" | "downgrade" | "warn";
+export type SourceSurface = "mcp" | "rest" | "sdk" | "cli" | "operator";
+export type SourceProfileId = "official_docs" | "code_activity" | "social_pulse" | "academic_research" | "market_finance" | "jobs_opportunities" | "government_regulatory" | "company_intel" | "composite_landscape" | "local_custom";
+export type ContextDecision = "use_first" | "cite_as_primary" | "cite_as_supporting" | "use_as_background" | "needs_verification" | "needs_refresh" | "watch_only" | "exclude";
+export type IntentProfileId = "citation_check" | "student_research" | "developer_adoption" | "job_search" | "market_watch" | "business_due_diligence" | "medical_literature_triage";
+export type ContextUtilityStatus = "success" | "partial" | "stale" | "failed" | "unknown";
+export interface SignalNormalizeOptions {
+    defaultSourceType?: string;
+    now?: Date | string;
+}
+export interface SourceProfile {
+    profile_id: SourceProfileId;
+    source_types: string[];
+    purpose: string;
+    default_decay_lambda: number;
+    half_life_hours: number;
+    authority_hint: SourceAuthorityHint;
+    date_policy: SourceDatePolicy;
+    failure_policy: SourceFailurePolicy;
+    recommended_surfaces: SourceSurface[];
+}
+export interface ContextDecisionOptions {
+    sourceProfile?: SourceProfile | SourceProfileId;
+    intentProfile?: IntentProfileId;
+}
+export interface ContextDecisionResult {
+    decision: ContextDecision;
+    label: string;
+    meaning: string;
+    action: string;
+    reasons: string[];
+    warnings: string[];
+}
+export interface HumanReadableHandoffResult {
+    safe_for_agent_handoff: boolean;
+    reason: string;
+}
+export interface HumanReadableContextResult {
+    label: string;
+    summary: string;
+    why: string[];
+    action: string;
+    warnings: string[];
+    handoff: HumanReadableHandoffResult;
+}
+export interface FreshContextSignalInput {
+    id?: string;
+    source: string;
+    source_type?: string;
+    title?: string;
+    content?: string;
+    published_at?: string | null;
+    content_date?: string | null;
+    retrieved_at?: string | null;
+    semantic_score?: number;
+    date_confidence?: SignalDateConfidence;
+    freshness_confidence?: SignalConfidence;
+    status?: ContextUtilityStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface FreshContextSignal {
+    contract_version: SignalContractVersion;
+    id?: string;
+    source: string;
+    source_type: string;
+    title?: string;
+    content?: string;
+    published_at: string | null;
+    retrieved_at: string;
+    semantic_score: number;
+    date_confidence: SignalDateConfidence;
+    status: ContextUtilityStatus;
+    metadata: Record<string, unknown>;
+    reasons: string[];
+}
+export interface FreshSignal {
+    id?: string;
+    source: string;
+    source_type?: string;
+    title?: string;
+    content?: string;
+    published_at?: string | null;
+    content_date?: string | null;
+    retrieved_at?: string | null;
+    semantic_score: number;
+    date_confidence?: SignalDateConfidence;
+    freshness_confidence?: SignalConfidence;
+    status?: ContextUtilityStatus;
+    metadata?: Record<string, unknown>;
+}
+export interface RankedSignal extends FreshSignal {
+    freshness_score: number | null;
+    final_score: number;
+    confidence: SignalConfidence;
+    reason: string;
+}
+export interface RankOptions {
+    semanticWeight?: number;
+    freshnessWeight?: number;
+    defaultSourceType?: string;
+    now?: Date | string;
+}
+export interface ContextUtilityInput {
+    contextualRelevance: number;
+    lambda: number;
+    ageHours: number;
+    dateConfidence?: SignalConfidence | "unknown";
+    status?: ContextUtilityStatus;
+}
+export interface ContextUtilityResult {
+    score: number;
+    contextualRelevance: number;
+    decayFactor: number;
+    dateConfidenceFactor: number;
+    statusFactor: number;
+    lambda: number;
+    ageHours: number;
+    status: ContextUtilityStatus;
+    reasons: string[];
+}
+export interface HaPriV2Input {
+    resultId: string;
+    rawContent: string;
+    semanticFingerprint?: string | null;
+    adapter: string;
+    publishedAt?: string | null;
+    retrievedAt?: string | null;
+    engineVersion: string;
+}
+export interface HaPriV2Material {
+    version: "FRESHCONTEXT_HA_PRI_V2";
+    resultId: string;
+    canonicalContentSha256: string;
+    semanticFingerprintSha256: string;
+    adapter: string;
+    publishedAt: string;
+    retrievedAt: string;
+    engineVersion: string;
+    signingPayload: string;
+}
+export interface HaPriV2Result extends HaPriV2Material {
+    haPriSigV2: string;
+}
+export type HaPriVerificationStatus = "valid" | "invalid" | "unknown";
+export interface HaPriV2VerificationResult {
+    status: HaPriVerificationStatus;
+    expected: string | null;
+    actual: string | null;
+    reasons: string[];
+}
+export type ProvenanceReadinessState = "complete" | "partial" | "incomplete" | "unknown" | "derived";
+export type ProvenanceSourceIdentityCompleteness = "complete" | "weak" | "missing" | "unusable";
+export type ProvenanceTimingCompleteness = "complete" | "partial" | "missing" | "unknown";
+export type ProvenanceReadinessInput = Partial<FreshContextSignalInput> | FreshContextSignal;
+export interface ProvenanceReadinessOptions extends SignalNormalizeOptions {
+    resultId?: string;
+    semanticFingerprint?: string | null;
+    engineVersion?: string;
+}
+export interface ProvenanceSourceIdentityResult {
+    source: string | null;
+    source_type: string | null;
+    result_id: string | null;
+    completeness: ProvenanceSourceIdentityCompleteness;
+}
+export interface ProvenanceReadinessResult {
+    state: ProvenanceReadinessState;
+    source_identity: ProvenanceSourceIdentityResult;
+    source_type: string | null;
+    published_at: string | null;
+    retrieved_at: string | null;
+    timing_confidence: SignalDateConfidence;
+    timing_completeness: ProvenanceTimingCompleteness;
+    canonical_content_sha256: string | null;
+    semantic_fingerprint_sha256: string | null;
+    ha_pri_v2: HaPriV2Result | null;
+    warnings: string[];
+    reasons: string[];
+}
+export interface CoreSignalProvenanceOptions {
+    resultId?: string;
+    semanticFingerprint?: string | null;
+    engineVersion?: string;
+}
+export interface CoreSignalEnvelopeResult {
+    context: FreshContext;
+    text: string;
+    structured: object;
+}
+export interface CoreSignalEvaluationOptions extends SignalNormalizeOptions, RankOptions {
+    includeEnvelope?: boolean;
+    envelopeMaxLength?: number;
+    envelopeFormat?: EnvelopeFormatOptions;
+    includeProvenance?: boolean;
+    provenance?: CoreSignalProvenanceOptions;
+}
+export interface CoreSignalEvaluationResult {
+    signal: FreshContextSignal;
+    freshness_score: number | null;
+    utility: ContextUtilityResult;
+    ranked: RankedSignal;
+    explanation: string;
+    envelope?: CoreSignalEnvelopeResult;
+    provenance?: HaPriV2Result;
+    provenance_readiness: ProvenanceReadinessResult;
+    reasons: string[];
+}

package/dist/core/utility.d.ts

@@ -0,0 +1,2 @@
+import type { ContextUtilityInput, ContextUtilityResult } from "./types.js";
+export declare function calculateContextUtility(input: ContextUtilityInput): ContextUtilityResult;

package/dist/rest/handler.d.ts

@@ -0,0 +1 @@
+export declare function handleRestRequest(request: Request): Promise<Response>;

package/dist/security.d.ts

@@ -0,0 +1,15 @@
+/**
+ * freshcontext-mcp security module
+ * Input sanitization, domain allowlists, and request validation
+ */
+export declare const ALLOWED_DOMAINS: Record<string, string[]>;
+export declare const MAX_URL_LENGTH = 500;
+export declare const MAX_QUERY_LENGTH = 200;
+export declare const MAX_PACKAGES_LENGTH = 300;
+export declare class SecurityError extends Error {
+    constructor(message: string);
+}
+export declare function validateUrl(rawUrl: string, adapterName: keyof typeof ALLOWED_DOMAINS): string;
+export declare function sanitizeQuery(query: string, maxLength?: number): string;
+export declare function sanitizePackages(input: string): string;
+export declare function formatSecurityError(err: unknown): string;

package/dist/security.js

@@ -10,9 +10,11 @@ export const ALLOWED_DOMAINS = {
     yc: ["www.ycombinator.com", "ycombinator.com"],
     repoSearch: [], // uses GitHub API directly, no browser
     packageTrends: [], // uses npm/PyPI APIs directly, no browser
-    reddit: [], // uses public Reddit JSON API, no browser
+    reddit: ["www.reddit.com", "reddit.com", "old.reddit.com"],
     finance: [], // uses Stooq quote API, no browser
+    arxiv: ["export.arxiv.org", "arxiv.org"],
     productHunt: ["www.producthunt.com", "producthunt.com"],
+    changelog: [], // accepts public changelog URLs but blocks private/internal targets
 };
 // ─── Blocked IP ranges and internal hostnames ────────────────────────────────
 const BLOCKED_PATTERNS = [

package/dist/server.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/server.js

@@ -23,7 +23,7 @@ import { EvaluateContextInputError, evaluateContextInput, formatEvaluateContextR
 import { formatSecurityError } from "./security.js";
 const server = new McpServer({
     name: "freshcontext-mcp",
-    version: "0.3.19",
+    version: "0.3.21",
 });
 const signalInputSchema = z.object({
     id: z.string().optional(),
@@ -46,7 +46,7 @@ server.registerTool("evaluate_context", {
     inputSchema: z.object({
         profile: z.string().min(1).describe("Source Profile id, e.g. academic_research, jobs_opportunities, market_finance, official_docs, local_custom."),
         intent: z.string().min(1).describe("Intent Profile id, e.g. citation_check, student_research, developer_adoption, job_search, market_watch, business_due_diligence, medical_literature_triage."),
-        signals: z.array(signalInputSchema).min(1).describe("Candidate context items provided by the caller. FreshContext evaluates these; it does not retrieve them."),
+        signals: z.array(signalInputSchema).min(1).max(100).describe("Candidate context items provided by the caller. FreshContext evaluates these; it does not retrieve them."),
         now: z.string().optional().describe("Optional ISO timestamp for deterministic evaluation."),
     }),
     annotations: { readOnlyHint: true, openWorldHint: false },

package/dist/tools/evaluateContext.d.ts

@@ -0,0 +1,21 @@
+import type { ContextDecisionResult, CoreSignalEvaluationResult, IntentProfileId, SourceProfile } from "../core/index.js";
+export declare class EvaluateContextInputError extends Error {
+    constructor(message: string);
+}
+export interface EvaluateContextInput {
+    profile: string;
+    intent: string;
+    signals: unknown;
+    now?: string;
+}
+export interface EvaluateContextItem {
+    evaluation: CoreSignalEvaluationResult;
+    decision: ContextDecisionResult;
+}
+export interface EvaluateContextResult {
+    profile: SourceProfile;
+    intent: IntentProfileId;
+    items: EvaluateContextItem[];
+}
+export declare function evaluateContextInput(input: EvaluateContextInput): EvaluateContextResult;
+export declare function formatEvaluateContextResult(result: EvaluateContextResult): string;

package/dist/tools/evaluateContext.js

@@ -1,4 +1,4 @@
-import { evaluateSignals, getSourceProfile, interpretEvaluations, } from "../core/index.js";
+import { evaluateSignals, getSourceProfile, interpretEvaluations, toReadableContextResult, } from "../core/index.js";
 const SUPPORTED_INTENTS = [
     "citation_check",
     "student_research",
@@ -8,6 +8,10 @@ const SUPPORTED_INTENTS = [
     "business_due_diligence",
     "medical_literature_triage",
 ];
+const MAX_CONTEXT_SIGNALS = 100;
+const MAX_SOURCE_CHARS = 2048;
+const MAX_TITLE_CHARS = 1000;
+const MAX_CONTENT_CHARS = 50000;
 export class EvaluateContextInputError extends Error {
     constructor(message) {
         super(message);
@@ -20,6 +24,12 @@ function isRecord(value) {
 function isIntentProfileId(value) {
     return SUPPORTED_INTENTS.includes(value);
 }
+function assertMaxLength(value, field, maxLength, index) {
+    if (typeof value === "string" && value.length > maxLength) {
+        const prefix = index === undefined ? "" : `signals[${index}].`;
+        throw new EvaluateContextInputError(`${prefix}${field} exceeds maximum length of ${maxLength} characters.`);
+    }
+}
 function validateSignal(value, index) {
     if (!isRecord(value)) {
         throw new EvaluateContextInputError(`signals[${index}] must be an object.`);
@@ -27,6 +37,9 @@ function validateSignal(value, index) {
     if (typeof value.source !== "string" || value.source.trim().length === 0) {
         throw new EvaluateContextInputError(`signals[${index}].source must be a non-empty string.`);
     }
+    assertMaxLength(value.source, "source", MAX_SOURCE_CHARS, index);
+    assertMaxLength(value.title, "title", MAX_TITLE_CHARS, index);
+    assertMaxLength(value.content, "content", MAX_CONTENT_CHARS, index);
     if ((typeof value.title !== "string" || value.title.trim().length === 0)
         && (typeof value.content !== "string" || value.content.trim().length === 0)) {
         throw new EvaluateContextInputError(`signals[${index}] must include title or content.`);
@@ -52,6 +65,12 @@ export function evaluateContextInput(input) {
     if (input.signals.length === 0) {
         throw new EvaluateContextInputError("signals must contain at least one candidate context item.");
     }
+    if (input.signals.length > MAX_CONTEXT_SIGNALS) {
+        throw new EvaluateContextInputError(`signals must contain at most ${MAX_CONTEXT_SIGNALS} candidate context items.`);
+    }
+    if (input.now !== undefined && Number.isNaN(new Date(input.now).getTime())) {
+        throw new EvaluateContextInputError("now must be a valid timestamp string when provided.");
+    }
     const signals = input.signals.map(validateSignal);
     const options = input.now ? { now: input.now } : {};
     const evaluations = evaluateSignals(signals, options);
@@ -120,6 +139,8 @@ export function formatEvaluateContextResult(result) {
             utility_score: item.evaluation.utility.score,
             confidence: item.evaluation.ranked.confidence,
             why: item.evaluation.explanation,
+            provenance_readiness: item.evaluation.provenance_readiness,
+            readable: toReadableContextResult(item.evaluation, item.decision),
         })),
     };
     lines.push("[FRESHCONTEXT_EVALUATION_JSON]", JSON.stringify(structured, null, 2), "[/FRESHCONTEXT_EVALUATION_JSON]");

package/dist/tools/freshnessStamp.d.ts

@@ -0,0 +1 @@
+export { LAMBDA, stampFreshness, toStructuredJSON, formatForLLM, } from "../core/index.js";

package/dist/types.d.ts

@@ -0,0 +1 @@
+export type { FreshContext, ExtractOptions, AdapterResult } from "./core/types.js";

package/docs/API_DESIGN.md

@@ -12,7 +12,7 @@ The REST host should expose the simplest useful path:
 
 1. User has raw retrieved signals.
 2. User sends those signals to FreshContext.
-3. Core evaluates freshness, confidence, ranking, explanation, optional envelope, and optional provenance.
+3. Core evaluates freshness, confidence, ranking, explanation, provenance readiness, optional envelope, and optional provenance.
 4. Host returns ranked context.
 5. Agent or app uses best context first.
 
@@ -122,6 +122,27 @@ Shape: `CoreSignalEvaluationResult`.
     "reason": "Strong semantic match and current freshness for blog."
   },
   "explanation": "Strong semantic match and current freshness for blog.",
+  "provenance_readiness": {
+    "state": "complete",
+    "source_identity": {
+      "source": "https://example.com/article",
+      "source_type": "blog",
+      "result_id": "sig_001",
+      "completeness": "complete"
+    },
+    "source_type": "blog",
+    "published_at": "2026-05-24T12:00:00.000Z",
+    "retrieved_at": "2026-05-24T13:00:00.000Z",
+    "timing_confidence": "high",
+    "timing_completeness": "complete",
+    "canonical_content_sha256": "abc123...",
+    "semantic_fingerprint_sha256": null,
+    "ha_pri_v2": null,
+    "warnings": [],
+    "reasons": [
+      "semantic fingerprint was not provided"
+    ]
+  },
   "envelope": {
     "context": {},
     "text": "[FRESHCONTEXT]...",
@@ -131,6 +152,8 @@ Shape: `CoreSignalEvaluationResult`.
 }
 ```
 
+`provenance_readiness` is always a Core judgment sidecar. It classifies source identity and timing completeness. It must not be used by the REST host to fetch, verify truth, reject context by policy, or change ranking.
+
 The REST host must not fetch upstream data, cache results, write D1, enforce Ha-Pri, or alter ranking policy.
 
 ## POST /v1/evaluate-batch
@@ -181,6 +204,9 @@ Evaluates and ranks multiple signals.
         "final_score": 0.85
       },
       "explanation": "Strong semantic match and current freshness for blog.",
+      "provenance_readiness": {
+        "state": "complete"
+      },
       "reasons": []
     }
   ]
@@ -342,6 +368,7 @@ Core owns:
 - timestamp/future-date/failure guards
 - freshness scoring
 - context utility sidecar
+- provenance readiness sidecar
 - default rank/explain behavior
 - optional envelope generation
 - optional Ha-Pri v2 material preparation

package/docs/CLIENT_SETUP.md

@@ -0,0 +1,166 @@
+# FreshContext Client Setup
+
+FreshContext is live as an MCP stdio package on npm.
+
+Use this guide when connecting Claude Desktop, Codex, or another MCP-compatible client to the published package.
+
+## What You Should See
+
+FreshContext `0.3.21` exposes:
+
+```text
+22 tools = evaluate_context + 21 read-only reference adapters
+```
+
+The primary interface is:
+
+```text
+evaluate_context
+```
+
+Use it when another retriever, agent, database, note parser, PDF extractor, or local script already has candidate context and needs FreshContext to judge what deserves to reach the model.
+
+## Claude Desktop: Published Package
+
+Add this to your Claude Desktop config, then restart Claude.
+
+macOS:
+
+```text
+~/Library/Application Support/Claude/claude_desktop_config.json
+```
+
+Windows:
+
+```text
+%APPDATA%\Claude\claude_desktop_config.json
+```
+
+Config:
+
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "npx",
+      "args": ["-y", "freshcontext-mcp@latest"]
+    }
+  }
+}
+```
+
+If you previously installed an older global package, refresh it:
+
+```bash
+npm install -g freshcontext-mcp@latest
+```
+
+Then this config is also valid when the global npm bin path is visible to Claude:
+
+```json
+{
+  "mcpServers": {
+    "freshcontext": {
+      "command": "freshcontext-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+## Codex: Local MCP Config
+
+For Codex local MCP config, use the published package through `npx`:
+
+```toml
+[mcp_servers.freshcontext]
+command = "npx"
+args = ["-y", "freshcontext-mcp@latest"]
+```
+
+If you prefer a source checkout while developing FreshContext itself:
+
+```toml
+[mcp_servers.freshcontext]
+command = "node"
+args = ["C:\\Users\\YOUR_USERNAME\\path\\to\\freshcontext-mcp\\dist\\server.js"]
+```
+
+Keep local MCP config files out of git. Do not commit machine-specific paths or credentials.
+
+## Source Checkout Setup
+
+Use this when contributing to FreshContext itself:
+
+```bash
+git clone https://github.com/PrinceGabriel-lgtm/freshcontext-mcp
+cd freshcontext-mcp
+npm install
+npm run build
+npm run smoke:stdio
+```
+
+Expected smoke result:
+
+```json
+{
+  "ok": true,
+  "package_version": "0.3.21",
+  "server_version": "0.3.21",
+  "tool_count": 22
+}
+```
+
+## Remote Worker Boundary
+
+The repository also declares a remote Streamable HTTP MCP endpoint:
+
+```text
+https://freshcontext-mcp.gimmanuel73.workers.dev/mcp
+```
+
+Some clients can use `mcp-remote`:
+
+```json
+{
+  "mcpServers": {
+    "freshcontext-remote": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
+    }
+  }
+}
+```
+
+The npm/local stdio package remains the safest default client path. The hosted Worker endpoint was verified on 2026-06-12 at `0.3.20 / 22 tools` with `evaluate_context` present and returning decision-first output. Because the Worker is a separate deployment surface, re-run remote verification before claiming future package interfaces are live there.
+
+## ChatGPT / OpenAI Connector Boundary
+
+Claude and Codex MCP paths are documented now.
+
+ChatGPT connector compatibility requires a separate search/fetch compatibility audit before being claimed. Do not assume ChatGPT connector support from Claude/Codex MCP compatibility alone.
+
+## Quick Test Prompt
+
+After connecting a client, ask it to use `evaluate_context` with this candidate context:
+
+```json
+{
+  "profile": "academic_research",
+  "intent": "citation_check",
+  "signals": [
+    {
+      "title": "Fresh research source",
+      "content": "A relevant academic source with a reliable publication date.",
+      "source": "https://arxiv.org/abs/2605.12345",
+      "source_type": "arxiv",
+      "published_at": "2026-05-24T12:00:00.000Z",
+      "retrieved_at": "2026-05-24T13:00:00.000Z",
+      "semantic_score": 0.94,
+      "date_confidence": "high"
+    }
+  ]
+}
+```
+
+Expected result: decision-first output with a decision, meaning, action, warnings, supporting scores, and a structured FreshContext evaluation JSON block.

package/docs/CODEX_MCP_USAGE.md

@@ -67,7 +67,7 @@ command = "npx"
 args = ["-y", "mcp-remote", "https://freshcontext-mcp.gimmanuel73.workers.dev/mcp"]
 ```
 
-This remote path was identified from repository metadata. The validation in this task verified local stdio only, not remote Codex compatibility, Worker availability, or Codex Cloud support.
+This remote path was verified on 2026-06-12 as a live Worker MCP endpoint exposing `0.3.20 / 22 tools`, including `evaluate_context`. That confirms Worker availability and MCP tool discovery. It does not by itself claim Codex Cloud support or guarantee every MCP client can use the remote bridge without its own client-specific setup check.
 
 ## Verification steps
 
@@ -83,8 +83,8 @@ Expected result:
 ```json
 {
   "ok": true,
-  "package_version": "0.3.19",
-  "server_version": "0.3.19",
+  "package_version": "0.3.21",
+  "server_version": "0.3.21",
   "tool_count": 22
 }
 ```
@@ -102,7 +102,7 @@ Expected result: no output and exit code 0.
 - Do not place secrets, credentials, registry tokens, npm tokens, GitHub tokens, or Cloudflare tokens in Codex MCP config.
 - Do not read, edit, print, or commit local token files, local environment files, registry credentials, Cloudflare local state, or Wrangler state.
 - Do not commit local Codex config or machine-specific paths.
-- Prefer the local stdio path for this compatibility check because it is verified by `npm run smoke:stdio`.
+- Prefer the local stdio path for source-checkout compatibility checks because it is verified by `npm run smoke:stdio`.
 - Do not claim Codex Cloud support unless it is separately tested and documented.
 
 ## Troubleshooting