deepseek-web-retrieval 0.6.0 → 0.7.0

package/src/core/descriptions.ts

@@ -16,7 +16,7 @@ export const SEARCH_RANKED_FILTERED =
 export const SEARCH_EMPTY_IS_NORMAL = "An empty result list is normal, not an error.";
 
 export const SEARCH_QUERY_OPERATORS =
-  "Use site:/-site: operators in the query to include or exclude domains; the full query must stay within 128 characters.";
+  "Use site:/-site: operators in the query to include or exclude domains, and after:/before: with a year or date (e.g. after:2025-06-01) to filter by publish time; the full query must stay within 128 characters.";
 
 /**
  * The full tool descriptions, composed from the fact fragments. Every host
@@ -38,6 +38,10 @@ export const FETCH_TOOL_DESCRIPTION =
 
 /** Parameter descriptions shared by every adapter's input schema for the two tools. */
 export const SEARCH_QUERY_PARAMETER =
-  "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:).";
+  "Search query, 128 characters or fewer including operators (site:, -site:, quoted phrases, lang:, after:, before:).";
+
+export const SEARCH_ORI_QUESTION_PARAMETER =
+  "The user's original question or task that triggered this search, in the user's own words rather than a " +
+  "reformulated query. Optional; 1-128 characters, and longer values are truncated.";
 
 export const FETCH_URL_PARAMETER = "Absolute http:// or https:// URL to fetch. Credentials are rejected.";

package/src/core/env.ts

@@ -1,4 +1,5 @@
-import { ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV } from "./constants";
+import { API_KEY_ENV, ENABLE_FETCH_ENV, ENABLE_SEARCH_ENV, SEARCH_LOCALIZATION_ENV } from "./constants";
+import { normalizeDomain } from "./domains";
 import { resolvePluginOptions } from "./options";
 import type { PluginOptions, ResolvedOptions } from "./types";
 
@@ -21,6 +22,7 @@ const NUMBER_ENV = {
 
 const TEXT_ENV = {
   language: "DEEPSEEK_SEARCH_LANGUAGE",
+  searchLocalization: SEARCH_LOCALIZATION_ENV,
 } as const;
 
 const DOMAINS_ENV = {
@@ -38,51 +40,92 @@ const FALSE_ONLY_ENV = {
   fetchEnabled: ENABLE_FETCH_ENV,
 } as const;
 
+/**
+ * Every option's `DEEPSEEK_*` variable name, in map order — the names a host that
+ * isolates its children from the parent environment (Codex) must forward for
+ * shell-set options to reach the server. `DEEPSEEK_API_KEY` is deliberately
+ * absent: it is not an option variable, and installers compose it separately.
+ */
+export const OPTION_ENV_VARS: readonly string[] = [
+  ...Object.values(NUMBER_ENV),
+  ...Object.values(TEXT_ENV),
+  ...Object.values(DOMAINS_ENV),
+  ...Object.values(FALSE_ONLY_ENV),
+];
+
 /**
  * Maps `DEEPSEEK_*` environment variables onto the shared plugin option keys and
  * resolves them through the shared pipeline, so defaults and clamping stay
  * identical across every adapter. Invalid values are dropped and the shared
- * default applies.
+ * default applies; `envOptionsReport` is where those drops become visible.
+ * `fileOptions` (the shared config file) layer beneath the environment: for
+ * the same key the environment wins.
  */
-export function resolveEnvOptions(env: Env = process.env): ResolvedOptions {
-  return resolvePluginOptions(pluginOptionsFromEnv(env));
+export function resolveEnvOptions(env: Env = process.env, fileOptions?: PluginOptions): ResolvedOptions {
+  return resolvePluginOptions({ ...fileOptions, ...pluginOptionsFromEnv(env) });
 }
 
-export function pluginOptionsFromEnv(env: Env): PluginOptions {
-  const options: Record<string, unknown> = {};
+/**
+ * What reading the `DEEPSEEK_*` environment produced, plus the problems as
+ * structured data. Startup paths stay silent (they use pluginOptionsFromEnv);
+ * surfaces whose job is visibility — the config command — replay these
+ * warnings through their own channel.
+ */
+export interface EnvOptionsReport {
+  readonly options: PluginOptions;
+  /** One entry per set-but-unusable `DEEPSEEK_*` variable: unknown names and values that had to be dropped. */
+  readonly warnings: readonly string[];
+}
 
-  putNumber(options, "count", env);
-  putNumber(options, "maxResults", env);
-  putNumber(options, "minRerank", env);
-  putNumber(options, "minAuthority", env);
-  putFalseOnly(options, "allowUnknownAuthority", env);
-  putDomains(options, "blockedDomains", env);
-  putDomains(options, "includeDomains", env);
+/** The options layer of the environment, with every drop reported instead of silent. */
+export function envOptionsReport(env: Env = process.env): EnvOptionsReport {
+  const options: Record<string, unknown> = {};
+  const warnings: string[] = [];
+
+  putNumber(options, "count", env, warnings);
+  putNumber(options, "maxResults", env, warnings);
+  putNumber(options, "minRerank", env, warnings);
+  putNumber(options, "minAuthority", env, warnings);
+  putFalseOnly(options, "allowUnknownAuthority", env, warnings);
+  putDomains(options, "blockedDomains", env, warnings);
+  putDomains(options, "includeDomains", env, warnings);
   putText(options, "language", env);
-  putNumber(options, "maxSummaryChars", env);
-  putNumber(options, "searchTimeoutMs", env);
-
-  putNumber(options, "fetchMaxChars", env);
-  putDomains(options, "fetchAllowedDomains", env);
-  putDomains(options, "fetchBlockedDomains", env);
-  putNumber(options, "fetchTimeoutMs", env);
-  putFalseOnly(options, "fetchBlockPrivateHosts", env);
-  putFalseOnly(options, "searchEnabled", env);
-  putFalseOnly(options, "fetchEnabled", env);
-
-  putNumber(options, "maxRetries", env);
-  putNumber(options, "retryBaseDelayMs", env);
+  putText(options, "searchLocalization", env);
+  putNumber(options, "maxSummaryChars", env, warnings);
+  putNumber(options, "searchTimeoutMs", env, warnings);
+
+  putNumber(options, "fetchMaxChars", env, warnings);
+  putDomains(options, "fetchAllowedDomains", env, warnings);
+  putDomains(options, "fetchBlockedDomains", env, warnings);
+  putNumber(options, "fetchTimeoutMs", env, warnings);
+  putFalseOnly(options, "fetchBlockPrivateHosts", env, warnings);
+  putFalseOnly(options, "searchEnabled", env, warnings);
+  putFalseOnly(options, "fetchEnabled", env, warnings);
+
+  putNumber(options, "maxRetries", env, warnings);
+  putNumber(options, "retryBaseDelayMs", env, warnings);
+
+  const known = new Set(OPTION_ENV_VARS);
+  for (const key of Object.keys(env)) {
+    if (!key.startsWith("DEEPSEEK_") || key === API_KEY_ENV || known.has(key)) continue;
+    if (!(env[key] ?? "").trim()) continue;
+    warnings.push(`unknown DEEPSEEK_* variable ${key} — ignored`);
+  }
+  return { options, warnings };
+}
 
-  return options;
+export function pluginOptionsFromEnv(env: Env): PluginOptions {
+  return envOptionsReport(env).options;
 }
 
-function putNumber(target: Record<string, unknown>, key: keyof typeof NUMBER_ENV, env: Env): void {
+function putNumber(target: Record<string, unknown>, key: keyof typeof NUMBER_ENV, env: Env, warnings: string[]): void {
   const value = env[NUMBER_ENV[key]];
   if (value === undefined) return;
   const trimmed = value.trim();
   if (!trimmed) return;
   const parsed = Number(trimmed);
   if (Number.isFinite(parsed)) target[key] = parsed;
+  else warnings.push(`${NUMBER_ENV[key]} is not a number ("${trimmed}") — ignored`);
 }
 
 function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, env: Env): void {
@@ -92,18 +135,42 @@ function putText(target: Record<string, unknown>, key: keyof typeof TEXT_ENV, en
   if (trimmed) target[key] = trimmed;
 }
 
-function putFalseOnly(target: Record<string, unknown>, key: keyof typeof FALSE_ONLY_ENV, env: Env): void {
-  if (isFalseValue(env[FALSE_ONLY_ENV[key]])) target[key] = false;
+function putFalseOnly(
+  target: Record<string, unknown>,
+  key: keyof typeof FALSE_ONLY_ENV,
+  env: Env,
+  warnings: string[],
+): void {
+  const name = FALSE_ONLY_ENV[key];
+  const value = env[name];
+  if (value === undefined || !value.trim()) return;
+  if (isFalseValue(value)) {
+    target[key] = false;
+    return;
+  }
+  warnings.push(`${name}="${value.trim()}" changes nothing — only false/0/no/off turns the switch off`);
 }
 
-function putDomains(target: Record<string, unknown>, key: keyof typeof DOMAINS_ENV, env: Env): void {
-  const value = env[DOMAINS_ENV[key]];
+function putDomains(
+  target: Record<string, unknown>,
+  key: keyof typeof DOMAINS_ENV,
+  env: Env,
+  warnings: string[],
+): void {
+  const name = DOMAINS_ENV[key];
+  const value = env[name];
   if (value === undefined || !value.trim()) return;
   const domains = value
     .split(",")
     .map((domain) => domain.trim())
     .filter((domain) => domain.length > 0);
+  for (const domain of domains) {
+    if (normalizeDomain(domain) === undefined) {
+      warnings.push(`${name} entry "${domain}" is not a domain — ignored`);
+    }
+  }
   if (domains.length > 0) target[key] = domains;
+  else warnings.push(`${name} contains no domains — ignored`);
 }
 
 function isFalseValue(value: string | undefined): boolean {

package/src/core/format.ts

@@ -95,7 +95,8 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
   return results
     .map((result, index) => {
       const title = result.title?.trim() || result.url;
-      const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})`];
+      const marker = formatQualityMarker(result);
+      const lines = [`${index + 1}. [${escapeBrackets(title)}](${result.url})${marker ? ` ${marker}` : ""}`];
       if (result.content) {
         lines.push(`   ${result.content.replaceAll("\n", " ")}`);
       }
@@ -107,6 +108,20 @@ export function formatSearchResults(results: readonly SearchResult[]): string {
     .join("\n\n");
 }
 
+/**
+ * Renders the quality fields DeepSeek reports as one bracketed token on the
+ * result's heading line; the text channel is the only one every host delivers
+ * to the model. Authority -1 means unknown and stays in the structured shape
+ * only, so it never wastes text.
+ */
+export function formatQualityMarker(result: SearchResult): string {
+  const parts: string[] = [];
+  if (result.rerankScore !== undefined) parts.push(`rerank ${result.rerankScore}`);
+  if (result.authority !== undefined && result.authority >= 0) parts.push(`authority ${result.authority}`);
+  if (result.siteName) parts.push(result.siteName);
+  return parts.length > 0 ? `[${parts.join(" · ")}]` : "";
+}
+
 /**
  * Renders one search result as the structured mirror of its text form; hosts
  * that read structuredContent (every JSON-replacing client excepted) get this
@@ -118,6 +133,9 @@ export function toStructuredResult(result: SearchResult) {
     ...(result.title ? { title: result.title } : {}),
     ...(result.content ? { content: result.content } : {}),
     ...(result.published !== undefined ? { published: result.published } : {}),
+    ...(result.rerankScore !== undefined ? { rerankScore: result.rerankScore } : {}),
+    ...(result.authority !== undefined ? { authority: result.authority } : {}),
+    ...(result.siteName ? { siteName: result.siteName } : {}),
   };
 }
 

package/src/core/options.ts

@@ -1,3 +1,4 @@
+import { isIP } from "node:net";
 import {
   DEFAULT_API_KEY_SOURCE,
   DEFAULT_FETCH_MAX_CHARS,
@@ -35,15 +36,21 @@ export function resolvePluginOptions(input?: PluginOptions): ResolvedOptions {
 }
 
 export function resolveSearchOptions(input?: PluginOptions): SearchOptions {
+  const count = clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50);
   return {
-    count: clampInt(input?.count, DEFAULT_SEARCH_COUNT, 1, 50),
-    maxResults: clampInt(input?.maxResults, DEFAULT_MAX_RESULTS, 0, 50),
+    count,
+    // Constraint: maxResults follows count only when the user left it alone —
+    // an explicit maxResults still caps as before. count never follows
+    // maxResults: fetching more than the cap returns wastes nothing visible,
+    // while returning fewer than were fetched silently discards results.
+    maxResults: clampInt(input?.maxResults, Number.isFinite(input?.count) ? count : DEFAULT_MAX_RESULTS, 0, 50),
     minRerank: finiteNumber(input?.minRerank, DEFAULT_MIN_RERANK),
     minAuthority: finiteNumber(input?.minAuthority, DEFAULT_MIN_AUTHORITY),
     allowUnknownAuthority: input?.allowUnknownAuthority !== false,
     blockedDomains: normalizeDomains(input?.blockedDomains),
     includeDomains: normalizeDomains(input?.includeDomains),
     language: optionalText(input?.language),
+    localization: localizationValue(input?.searchLocalization),
     maxSummaryChars: clampInt(input?.maxSummaryChars, DEFAULT_MAX_SUMMARY_CHARS, 0, 1_000_000),
     timeoutMs: clampInt(input?.searchTimeoutMs, DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS),
     enabled: input?.searchEnabled !== false,
@@ -93,6 +100,19 @@ function optionalText(value: unknown): string | undefined {
   return trimmed ? trimmed : undefined;
 }
 
+/**
+ * Constraint: only a valid IPv4 dotted-quad (four 0-255 octets) or IPv6
+ * address (including "::" compression) survives; anything else drops to
+ * undefined so the request omits `localization` entirely. This is the
+ * enforcement point no matter which config channel delivered the value.
+ */
+function localizationValue(value: unknown): string | undefined {
+  const text = optionalText(value);
+  // isIP is the platform's strict parser; its one lax spot is IPv6 zone IDs
+  // ("%eth0"), which name a local link, not a geolocation — reject those.
+  return text !== undefined && !text.includes("%") && isIP(text) !== 0 ? text : undefined;
+}
+
 function finiteNumber(value: unknown, fallback: number): number {
   return typeof value === "number" && Number.isFinite(value) ? value : fallback;
 }

package/src/core/search.ts

@@ -67,11 +67,17 @@ export function processResults(raw: readonly DeepSeekSearchResult[], options: Se
     const content = truncate(optionalText(item.summary) ?? optionalText(item.snippet) ?? "", options.maxSummaryChars);
     const published = parsePublished(item.date);
     const title = optionalText(item.title);
+    const rerankScore = typeof rerank === "number" && Number.isFinite(rerank) ? rerank : undefined;
+    const authorityScore = typeof authority === "number" && Number.isFinite(authority) ? authority : undefined;
+    const siteName = optionalText(item.site_name);
     results.push({
       url,
       ...(title ? { title } : {}),
       ...(content ? { content } : {}),
       ...(published !== undefined ? { published } : {}),
+      ...(rerankScore !== undefined ? { rerankScore } : {}),
+      ...(authorityScore !== undefined ? { authority: authorityScore } : {}),
+      ...(siteName ? { siteName } : {}),
     });
   }
 

package/src/core/types.ts

@@ -13,6 +13,12 @@ export interface SearchOptions {
   readonly blockedDomains: readonly string[];
   readonly includeDomains: readonly string[];
   readonly language?: string;
+  /**
+   * Deployment-level only — never a per-call tool parameter. A valid IPv4 or
+   * IPv6 address sent as DeepSeek's optional `localization` to prefer
+   * geo-localized results; invalid values are dropped at option resolution.
+   */
+  readonly localization?: string;
   readonly maxSummaryChars: number;
   readonly timeoutMs: number;
   readonly enabled: boolean;
@@ -46,6 +52,7 @@ export interface ResolvedOptions {
 export interface DeepSeekSearchResult {
   readonly rerank_score?: number;
   readonly authority?: number;
+  readonly site_name?: string | null;
   readonly title?: string | null;
   readonly url?: string | null;
   readonly snippet?: string | null;
@@ -59,6 +66,10 @@ export interface SearchResult {
   readonly title?: string;
   readonly content?: string;
   readonly published?: number;
+  readonly rerankScore?: number;
+  /** Faithful to the wire: -1 means unknown authority. */
+  readonly authority?: number;
+  readonly siteName?: string;
 }
 
 export interface FetchedPage {

package/src/installer/cli.ts

@@ -1,10 +1,14 @@
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { userConfigHome } from "../core/config-file";
+import type { Env } from "../core/env";
 import { TOOL_VERSION } from "../version";
 import { ApplyError, applyPlan } from "./apply";
+import { runConfigCommand } from "./config-command";
 import { HOST_PLANNERS, HOST_VERSION_PROBES, planForHost } from "./hosts";
+import { pinPackageRef } from "./ownership";
 import { renderPlan } from "./render";
-import { listRecords } from "./state";
+import { legacyGlobalStateDir, listRecords, readingLegacyGlobalRecords } from "./state";
 import type { HostName, InstallerInput, Scope, Tier } from "./types";
 import { uninstall } from "./uninstall";
 
@@ -20,9 +24,10 @@ const EXIT_RECOVERY = 3;
 const USAGE = `Usage:
   deepseek-web-retrieval init --host ${HOST_CHOICES} --scope <project|global> \
 --search <optional|preferred|forced|off> --fetch <optional|preferred|forced|off> \
-[--path <extension|mcp>] [--package <npm ref>] [--cwd <dir>] [--apply]
+[--path <extension|mcp>] [--package <npm ref>] [--pin] [--cwd <dir>] [--apply]
   deepseek-web-retrieval uninstall --host ${HOST_CHOICES} --scope <project|global> [--cwd <dir>]
   deepseek-web-retrieval list [--cwd <dir>]
+  deepseek-web-retrieval config [--search <query>]
   deepseek-web-retrieval version
 
 init prints the full plan (every file, old value → new value) and writes nothing
@@ -31,7 +36,17 @@ the integration mechanism for hosts with more than one (Pi: extension by
 default, mcp for the stdio MCP server). --package overrides the package ref
 written into host config; the Pi extension path turns it into the packages
 source (a bare name is prefixed with npm:, a ref that already starts with npm:
-is written as-is).
+is written as-is). --pin appends the running CLI's version to the package ref
+(a ref already ending in a version keeps it), so hosts resolve that exact
+release instead of the latest publish; re-run init --pin to move the pin.
+
+config prints the effective configuration — every knob with its value and its
+source (default, shared file, or environment), resolved the way the MCP server
+resolves it — and exits 1 when the config file or the DEEPSEEK_* environment
+has problems (unknown or rejected keys, unparseable JSON, set-but-unusable
+variable values; a missing file is fine). config --search <query>
+runs one billed search through that configuration to verify the key, config,
+and network end to end; it exits 1 when the key is missing or the search fails.
 
 Exit codes: 0 success; 1 refused or failed with nothing written (a failed apply
 is fully rolled back); 2 invalid command line; 3 recovery required — a failed
@@ -45,7 +60,7 @@ interface Flags {
 }
 
 const VALUE_FLAGS = new Set(["host", "scope", "search", "fetch", "path", "package", "cwd"]);
-const BOOLEAN_FLAGS = new Set(["apply"]);
+const BOOLEAN_FLAGS = new Set(["apply", "pin"]);
 const PATH_CHOICES: readonly ["extension", "mcp"] = ["extension", "mcp"];
 
 function parseFlags(args: readonly string[]): Flags {
@@ -99,6 +114,8 @@ function parseFlags(args: readonly string[]): Flags {
 export interface CliIo {
   readonly out?: (line: string) => void;
   readonly err?: (line: string) => void;
+  /** Platform the CLI resolves paths for; tests pin "win32" on any host. */
+  readonly platform?: NodeJS.Platform;
 }
 
 /** CLI entry for the init/uninstall/list subcommands; returns the process exit code. */
@@ -126,12 +143,14 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
   }
   const cwd = resolve(flags.values.get("cwd") ?? process.cwd());
   const home = process.env.HOME ?? homedir();
-  const configHome = resolveConfigHome(home);
+  const platform = io.platform ?? process.platform;
+  const roots = { home, cwd, platform } as const;
+  const configHome = resolveConfigHome(process.env, home, platform);
 
   if (command === "list") {
     let records: ReturnType<typeof listRecords>;
     try {
-      records = listRecords({ home, cwd, configHome });
+      records = listRecords({ ...roots, configHome });
     } catch (error) {
       err(error instanceof Error ? error.message : String(error));
       return 1;
@@ -140,6 +159,12 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
       out("No installs recorded.");
       return 0;
     }
+    if (readingLegacyGlobalRecords({ ...roots, configHome })) {
+      out(
+        `Global install records are being read from the legacy ${legacyGlobalStateDir(roots)} ` +
+          "(written before the Windows config home moved to %APPDATA%).",
+      );
+    }
     for (const record of records) {
       const by = record.installerVersion ? ` by v${record.installerVersion}` : "";
       out(
@@ -150,8 +175,12 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
     return 0;
   }
 
+  if (command === "config") {
+    return runConfigCommand(flags.values.get("search"), { out, err });
+  }
+
   if (command === "uninstall") {
-    const required = requireInput(flags, cwd, home, configHome, false);
+    const required = requireInput(flags, cwd, home, configHome, platform, false);
     if (!required.ok) return usageError(required.problems, err);
     try {
       for (const line of uninstall(required.input)) out(line);
@@ -167,7 +196,7 @@ export async function runInstallerCli(argv: readonly string[], io: CliIo = {}):
     return EXIT_USAGE;
   }
 
-  const required = requireInput(flags, cwd, home, configHome, true);
+  const required = requireInput(flags, cwd, home, configHome, platform, true);
   if (!required.ok) return usageError(required.problems, err);
   const { input } = required;
   const probe = HOST_VERSION_PROBES[input.host];
@@ -205,13 +234,15 @@ function usageError(problems: readonly string[], err: (line: string) => void): n
 }
 
 /**
- * XDG_CONFIG_HOME is honored only when it belongs to the real home; the one
- * environment read happens here, at the edge, and flows down as explicit input.
+ * The installer edge's one config-home resolution, built on the canonical
+ * helper (userConfigHome): an inherited XDG_CONFIG_HOME is honored only when it
+ * belongs to the real home — a rewritten HOME must not smuggle in someone
+ * else's config root — and every other case takes the helper's platform
+ * default (win32: %APPDATA% or `<home>\AppData\Roaming`; otherwise ~/.config).
  */
-function resolveConfigHome(home: string): string | undefined {
-  const xdg = process.env.XDG_CONFIG_HOME;
-  if (xdg && home === (process.env.HOME ?? "")) return xdg;
-  return undefined;
+export function resolveConfigHome(env: Env, home: string, platform: NodeJS.Platform = process.platform): string {
+  const xdgTrusted = env.XDG_CONFIG_HOME !== undefined && env.XDG_CONFIG_HOME !== "" && home === (env.HOME ?? "");
+  return userConfigHome({ env: xdgTrusted ? env : { ...env, XDG_CONFIG_HOME: undefined }, home, platform });
 }
 
 type RequireInputResult =
@@ -222,7 +253,8 @@ function requireInput(
   flags: Flags,
   cwd: string,
   home: string,
-  configHome: string | undefined,
+  configHome: string,
+  platform: NodeJS.Platform,
   needsTiers: boolean,
 ): RequireInputResult {
   const problems: string[] = [];
@@ -262,6 +294,7 @@ function requireInput(
   }
   if (home === "") problems.push("HOME is not set and the user home cannot be resolved; cannot proceed");
   if (problems.length > 0) return { ok: false, problems };
+  const packageRef = flags.values.get("package") ?? "deepseek-web-retrieval";
   return {
     ok: true,
     input: {
@@ -269,10 +302,11 @@ function requireInput(
       scope: scope as Scope,
       search: search as Tier,
       fetch: fetch as Tier,
-      packageRef: flags.values.get("package") ?? "deepseek-web-retrieval",
+      packageRef: flags.booleans.has("pin") ? pinPackageRef(packageRef, TOOL_VERSION) : packageRef,
       home,
       cwd,
       configHome,
+      platform,
       ...(path !== undefined ? { path: path as "extension" | "mcp" } : {}),
     },
   };

package/src/installer/config-command.ts

@@ -0,0 +1,116 @@
+import { apiKeyFromEnv, MISSING_API_KEY_MESSAGE } from "../core/auth";
+import { createRetrievalClient, type RetrievalClient } from "../core/client";
+import { configFilePath, readFileOptionsReport } from "../core/config-file";
+import { configSummaryValues, formatConfigValue } from "../core/config-summary";
+import type { Env } from "../core/env";
+import { envOptionsReport, resolveEnvOptions } from "../core/env";
+import { formatSearchResults } from "../core/format";
+
+const EXIT_CONFIG_PROBLEMS = 1;
+const EXIT_USAGE = 2;
+
+const HOST_OVERRIDE_NOTE =
+  "Host-native layers (OpenCode options, Pi settings) may override file and env values per host.";
+
+/** Where the config command writes; the installer CLI resolves its CliIo into this. */
+export interface ConfigCommandIo {
+  readonly out: (line: string) => void;
+  readonly err: (line: string) => void;
+}
+
+/** Injectable seams: the environment to resolve, and the client for --search. */
+export interface ConfigCommandDeps {
+  readonly env?: Env;
+  readonly client?: RetrievalClient;
+}
+
+/**
+ * The `config` subcommand: the user-facing arm of configuration visibility.
+ * Prints the effective options exactly as the MCP server would resolve them
+ * (defaults < shared file < environment), each knob with its value and source,
+ * and replays the problems that would only whisper past on stderr at runtime —
+ * shared-file problems and set-but-unusable `DEEPSEEK_*` variables alike. With
+ * `query` set, runs one real billed search through that config — the
+ * end-to-end verifier for key, config, and network. Returns the exit code: 0
+ * normally, 1 for file or environment problems (plain form) or a failed
+ * search, 2 for a blank --search query. A missing file is not a problem.
+ */
+export async function runConfigCommand(
+  query: string | undefined,
+  io: ConfigCommandIo,
+  deps: ConfigCommandDeps = {},
+): Promise<number> {
+  if (query !== undefined && !query.trim()) {
+    io.err('error: --search requires a query (for example: config --search "deepseek mcp")');
+    return EXIT_USAGE;
+  }
+
+  const env = deps.env ?? process.env;
+  const file = configFilePath({ env });
+  const report = readFileOptionsReport(file);
+  for (const warning of report.warnings) io.err(`warning: ${warning}`);
+  const envReport = envOptionsReport(env);
+  for (const warning of envReport.warnings) io.err(`warning: ${warning}`);
+
+  // The same layers, in the same order, as the MCP server's startup resolution.
+  const resolved = resolveEnvOptions(env, report.options);
+
+  if (query === undefined) {
+    printConfigReport(file, report.exists, report.options, envReport.options, resolved, io);
+    return report.warnings.length > 0 || envReport.warnings.length > 0 ? EXIT_CONFIG_PROBLEMS : 0;
+  }
+
+  const apiKey = apiKeyFromEnv(env);
+  if (!apiKey) {
+    io.err(MISSING_API_KEY_MESSAGE);
+    return EXIT_CONFIG_PROBLEMS;
+  }
+  const client = deps.client ?? createRetrievalClient();
+  const startedAt = Date.now();
+  try {
+    const results = await client.searchWeb(query, resolved.search, {
+      signal: new AbortController().signal,
+      auth: { apiKey },
+      retry: resolved.retry,
+    });
+    const elapsedMs = Date.now() - startedAt;
+    io.out(
+      `search "${query.trim()}" — ${results.length} ${results.length === 1 ? "result" : "results"} in ${elapsedMs} ms`,
+    );
+    io.out("");
+    for (const line of formatSearchResults(results).split("\n")) io.out(line);
+    return 0;
+  } catch (error) {
+    io.err(error instanceof Error ? error.message : String(error));
+    return EXIT_CONFIG_PROBLEMS;
+  }
+}
+
+/** The knob table, in the vocabulary order the startup deviation summary uses. */
+function printConfigReport(
+  file: string,
+  exists: boolean,
+  fileOptions: Readonly<Record<string, unknown>>,
+  envOptions: Readonly<Record<string, unknown>>,
+  resolved: ReturnType<typeof resolveEnvOptions>,
+  io: ConfigCommandIo,
+): void {
+  io.out(`Config file: ${file} (${exists ? "exists" : "missing"})`);
+  io.out("");
+  const effective = configSummaryValues(resolved);
+  const fileKeys = new Set(Object.keys(fileOptions));
+  const envKeys = new Set(Object.keys(envOptions));
+  for (const name of Object.keys(effective)) {
+    // The environment wins over the file for the same key, exactly as resolution does.
+    let source = envKeys.has(name) ? "env" : fileKeys.has(name) ? "file" : "default";
+    // maxResults follows the effective count when unset (options.ts), so when
+    // the count knob was configured its derived value is not "default" — its
+    // source is the count setting that drove it.
+    if (name === "maxResults" && source === "default" && (envKeys.has("count") || fileKeys.has("count"))) {
+      source = "count";
+    }
+    io.out(`${name} = ${formatConfigValue(effective[name], "join")} (${source})`);
+  }
+  io.out("");
+  io.out(HOST_OVERRIDE_NOTE);
+}

package/src/installer/hosts/codex.ts

@@ -1,5 +1,6 @@
 import { spawnSync } from "node:child_process";
 import { API_KEY_ENV } from "../../core/constants";
+import { OPTION_ENV_VARS } from "../../core/env";
 import { FORCED_COST_NOTE, othersStayRegisteredNote, replacingExistingEntryNote, splitCompetitors } from "../detect";
 import { codecFor } from "../formats";
 import { buildRulesBlock } from "../formats/rules";
@@ -111,7 +112,7 @@ export function planCodex(input: InstallerInput, _previous: InstallRecord | unde
     command: "npx",
     args: ["-y", input.packageRef],
     ...(keptDisabled.length > 0 || offDisabled.length > 0 ? { disabled_tools: [...keptDisabled, ...offDisabled] } : {}),
-    env_vars: [API_KEY_ENV],
+    env_vars: [API_KEY_ENV, ...OPTION_ENV_VARS],
   };
 
   const ops: ConfigOp[] = [{ op: "set", path: ["mcp_servers", "deepseek"], value: entry, previous: existingEntry }];
@@ -133,8 +134,9 @@ export function planCodex(input: InstallerInput, _previous: InstallRecord | unde
   edits.push({ file: paths.config, format: "toml", shared: true, ops });
 
   notes.push(
-    `Codex stdio children do not inherit the parent environment, so the entry forwards ${API_KEY_ENV} explicitly ` +
-      "via env_vars; the key must be set in the shell that launches Codex.",
+    `Codex stdio children do not inherit the parent environment, so the entry forwards ${API_KEY_ENV} and every ` +
+      "DEEPSEEK_* option variable explicitly via env_vars; shell-set knobs reach the server without hand-editing " +
+      "config.toml (the shared config file works without any forwarding).",
   );
   if (input.scope === "project") {
     notes.push(