@lincoln504/pi-research 1.0.2 → 1.0.3

package/README.md

@@ -63,7 +63,7 @@ pi install npm:@lincoln504/pi-research
 
 See [Agent skill](docs/AGENT-SKILL.md) or [SDK](docs/SDK.md) for standalone (no pi extension) installation.
 
-Then configure a model and key — set `PI_RESEARCH_MODEL` (e.g. `openai/gpt-4o`) plus `PI_RESEARCH_API_KEY` and `PI_RESEARCH_PROVIDER`, either as environment variables or in `~/.pi/research/config.env`. See [Configuration](docs/CONFIGURATION.md). (The pi extension needs no key — it uses pi's own auth.)
+The pi extension works out of the box — it runs on your pi session's model and pi's own configuration. Standalone use (agent skill / CLI / SDK) requires a configured model: set `PI_RESEARCH_MODEL` (e.g. `openai/gpt-4o`) as an environment variable or in `~/.pi/research/config.env`, plus `PI_RESEARCH_API_KEY` if you don't use pi. See [Configuration](docs/CONFIGURATION.md).
 
 The first install pulls the stealth browser engine, which takes a few minutes.
 

package/dist/cli.mjs

@@ -22000,14 +22000,15 @@ async function _doInit(options = {}) {
   }
   globalApiKey = options.apiKey || process.env["PI_RESEARCH_API_KEY"];
   let parsedProvider = options.provider || process.env["PI_RESEARCH_PROVIDER"];
-  if (!parsedProvider && options.model) {
-    if (typeof options.model === "string") {
-      const slashIdx = options.model.indexOf("/");
+  const effectiveModel = options.model ?? globalConfig.RESEARCH_MODEL;
+  if (!parsedProvider && effectiveModel) {
+    if (typeof effectiveModel === "string") {
+      const slashIdx = effectiveModel.indexOf("/");
       if (slashIdx > 0) {
-        parsedProvider = options.model.slice(0, slashIdx);
+        parsedProvider = effectiveModel.slice(0, slashIdx);
       }
-    } else if (options.model.provider) {
-      parsedProvider = options.model.provider;
+    } else if (effectiveModel.provider) {
+      parsedProvider = effectiveModel.provider;
     }
   }
   if (globalApiKey && !parsedProvider) {
@@ -22015,7 +22016,16 @@ async function _doInit(options = {}) {
   }
   globalRegistry = buildModelRegistry(globalApiKey, parsedProvider);
   try {
-    globalModel = resolveModel(globalRegistry, typeof options.model === "string" ? options.model : void 0, parsedProvider, globalApiKey);
+    if (effectiveModel && typeof effectiveModel === "object" && effectiveModel.id) {
+      globalModel = effectiveModel;
+    } else {
+      globalModel = resolveModel(
+        globalRegistry,
+        typeof effectiveModel === "string" ? effectiveModel : void 0,
+        parsedProvider,
+        globalApiKey
+      );
+    }
     globalContainer = getServiceContainer();
     registerCoreServices(globalContainer);
     registerInfrastructureServices(globalContainer);
@@ -22630,6 +22640,18 @@ function detectCredentials() {
     };
   }
   if (piAuthPresent) {
+    if (!model) {
+      return {
+        source: "pi-config",
+        apiKeyConfigured: true,
+        provider,
+        model,
+        modelFrom,
+        piAuthPresent,
+        piModelsPresent,
+        problem: 'pi credentials were found (auth.json), but no research model is configured. The standalone CLI / agent skill run only on an explicitly configured model \u2014 they do not follow the model selected inside the pi extension. Set PI_RESEARCH_MODEL to a "provider/model-id" (in the environment, or in config.env / cli.env below).'
+      };
+    }
     return {
       source: "pi-config",
       apiKeyConfigured: true,
@@ -22659,14 +22681,14 @@ function configBlock(det, extraNote) {
   lines.push(`  \u2022 base config file:   ${paths.configEnv}`);
   lines.push(`  \u2022 cli overlay:        ${paths.cliIfaceEnv}  (optional; overrides base for this CLI / agent skill)`);
   lines.push(`  \u2022 env vars:           PI_RESEARCH_API_KEY / PI_RESEARCH_PROVIDER / PI_RESEARCH_MODEL`);
-  lines.push(`  \u2022 pi auth storage:    ${paths.piAuth}`);
-  lines.push(`  \u2022 pi models:          ${paths.piModels}`);
+  lines.push(`  \u2022 pi config (keys):   ${paths.piAuth}`);
+  lines.push(`  \u2022 pi config (models): ${paths.piModels}`);
   lines.push("");
   lines.push("Detected:");
   lines.push(`  \u2022 credential source:  ${det.source}`);
   lines.push(`  \u2022 api key configured: ${det.apiKeyConfigured}`);
-  lines.push(`  \u2022 provider:           ${det.provider ?? "(unset)"}`);
-  lines.push(`  \u2022 model:              ${det.model ?? "(unset)"}  [from: ${det.modelFrom}]`);
+  lines.push(`  \u2022 provider:           ${det.provider ?? "(unset \u2014 inferred from a provider/model-id model)"}`);
+  lines.push(`  \u2022 model:              ${det.model ? `${det.model}  [from: ${det.modelFrom}]` : "(not set \u2014 set PI_RESEARCH_MODEL, required)"}`);
   lines.push(`  \u2022 pi auth.json:       ${det.piAuthPresent ? "present" : "absent"}`);
   lines.push(`  \u2022 pi models.json:     ${det.piModelsPresent ? "present" : "absent"}`);
   if (extraNote) lines.push(`  \u2022 note:               ${extraNote}`);
@@ -22923,8 +22945,9 @@ uninstall: ${BINARY_NAME} skill uninstall
     } catch (err) {
       return reportError(err, "skill install", s.json);
     }
+    const skillModel = process.env["PI_RESEARCH_MODEL"] ?? getConfig(process.cwd(), "cli").RESEARCH_MODEL;
     if (s.json) {
-      toStdout(pretty({ command: "skill", action: "install", dryRun: !!s.dryRun, results: results2 }));
+      toStdout(pretty({ command: "skill", action: "install", dryRun: !!s.dryRun, results: results2, modelConfigured: Boolean(skillModel) }));
     } else {
       toStdout(`pi-research agent skill \u2014 ${s.dryRun ? "install (dry run)" : "install"}
 
@@ -22934,6 +22957,15 @@ uninstall: ${BINARY_NAME} skill uninstall
       toStdout(`
 The skill activates automatically \u2014 ask the agent to research something.
 `);
+      if (!skillModel) {
+        toStdout(
+          `
+Required: set PI_RESEARCH_MODEL=provider/model-id in ${resolvedConfigPaths().configEnv}
+(or as an env var) \u2014 the skill runs only on this configured model, not your pi
+session model. Verify with: ${BINARY_NAME} status
+`
+        );
+      }
     }
     return results2.some((r) => r.status === "error") ? EXIT.SOFTWARE : EXIT.OK;
   }
@@ -23091,11 +23123,15 @@ COMMANDS
 CONFIGURE
   Credentials are resolved in this order (first match wins):
 
-    env vars:     PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
-    cli overlay:  ${p.cliIfaceEnv}   (optional; this CLI / agent skill only)
-    base config:  ${p.configEnv}
-    pi auth:      ${p.piAuth}
-    pi models:    ${p.piModels}
+    env vars:            PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
+    cli overlay:         ${p.cliIfaceEnv}   (optional; this CLI / agent skill only)
+    base config:         ${p.configEnv}
+    pi config (keys):    ${p.piAuth}
+    pi config (models):  ${p.piModels}
+
+  A model is REQUIRED: set PI_RESEARCH_MODEL to a "provider/model-id". This CLI and
+  the agent skill run only on that configured model \u2014 they do not follow the model
+  selected inside the pi extension.
 
   The pi extension has its own optional overlay file:
     pi extension: ${p.piIfaceEnv}

package/docs/AGENT-SKILL.md

@@ -10,7 +10,8 @@ pi-research software.
 Already running the `pi` extension (`pi install npm:@lincoln504/pi-research`)? You
 already have the engine — install the skill into your other agents with
 `/research-config` → Install in External Agents (see [Installation flow](#installation-flow))
-and skip the rest.
+and skip the install commands below. The model step still applies to you: the
+skill runs on its own configured `PI_RESEARCH_MODEL`, not your pi session's model.
 
 For standalone use without pi, install the engine globally, then link the skill into
 every coding agent detected on this machine:
@@ -24,6 +25,18 @@ pi-research skill install                # link the skill into Claude, Codex, Op
 different skill in the slot, and records what it created so `pi-research skill uninstall`
 removes exactly that. Run `pi-research skill status` to see where it is installed.
 
+Then configure the model research runs on — the skill and standalone CLI use only
+this explicitly configured model (they never follow the model selected inside the
+pi extension) and refuse to start without one:
+
+```sh
+# ~/.pi/research/config.env  (or export as an env var)
+PI_RESEARCH_MODEL=provider/model-id
+```
+
+If you use `pi`, the API key comes from your pi configuration (`~/.pi/agent/auth.json`) automatically; otherwise
+also set `PI_RESEARCH_API_KEY` (same file or env var). See [Configuration](CONFIGURATION.md).
+
 On Windows, run `pi-research` from `cmd` or use `pi-research.cmd`: PowerShell's default
 execution policy (`Restricted`) blocks npm's `.ps1` shims ("running scripts is
 disabled"); or run `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned` once.
@@ -114,8 +127,8 @@ Manual. Symlink the directory into any agent's skills folder yourself:
 ### Prerequisites
 
 - Node.js >= 22.19.0
-- `pi-research` installed where the launcher can find it, plus a model + API key.
-  See [Configuration](CONFIGURATION.md).
+- `pi-research` installed where the launcher can find it, plus a configured model
+  (`PI_RESEARCH_MODEL`) + API key. See [Configuration](CONFIGURATION.md).
 
 ```bash
 npm install -g @lincoln504/pi-research

package/docs/CONFIGURATION.md

@@ -75,7 +75,7 @@ Research
 | `PI_RESEARCH_RETRY_DELAY_MS` | `2000` | 100–10000 | Base delay between retries. |
 | `PI_RESEARCH_WORKER_THREADS` | `4` | 1–10 | Browser worker processes. Higher = more throughput, more CPU/RAM. |
 | `PI_RESEARCH_WORKER_CONCURRENCY` | `2` | 1–10 | Tasks per worker process. |
-| `PI_RESEARCH_MODEL` | _(session model)_ | — | Model override for researcher sub-agents (deep and quick) and knowledge synthesis. In the pi extension the coordinator and evaluator keep using the session model; on the standalone CLI/SDK, when no `--model`/`model` option is given, this also selects the session model itself. Accepts `provider/id` or a bare model id. |
+| `PI_RESEARCH_MODEL` | _(pi: session model; CLI/skill: required)_ | — | The model research runs on. **Required for the standalone CLI / agent skill** — they use only this configured model (never the model selected inside the pi extension) and refuse to start without one. On the SDK it selects the session model when no `model` option is given. In the pi extension it overrides researcher sub-agents and knowledge synthesis, while the coordinator and evaluator keep using the session model. Accepts `provider/id` or a bare model id. |
 | `PI_RESEARCH_DISABLED_TOOLS` | _(none)_ | — | Comma-separated research tools to disable for a run (`search`, `scrape`, `security_search`, `stackexchange`, `youtube_transcript`, `grep`). Removed from every researcher's toolset and named in the coordinator/evaluator prompt. |
 | `PI_RESEARCH_REPORT_EXPORT_ENABLED` (TUI) | `false` | — | Front-ends write a Markdown report to disk and surface its path. |
 | `PI_RESEARCH_REPORT_EXPORT_DIR` | _(smart cwd)_ | — | Pin exported reports to a fixed directory, bypassing the cwd-relative resolution. Useful for the agent skill, which runs from the host agent's arbitrary directory. |
@@ -128,11 +128,11 @@ See the [knowledge store doc](KNOWLEDGE-STORE.md) for what each value does.
 | `PI_RESEARCH_EMBEDDING_MODEL_INIT_TIMEOUT_MS` | `300000` | 10000–600000 | Embedding-model initialization timeout (first-time download can be slow). |
 | `PI_RESEARCH_WEBGPU_REPROBE` | _(unset)_ | — | Set `1` to discard the cached WebGPU-viability verdict and probe again on next use. |
 
-API keys (all optional)
+API keys
 
 | Variable | Description |
 |----------|-------------|
-| `PI_RESEARCH_API_KEY` / `PI_RESEARCH_PROVIDER` | Explicit LLM credentials for SDK / CLI mode (not needed when using pi's own auth). Provider is required alongside the key. |
+| `PI_RESEARCH_API_KEY` / `PI_RESEARCH_PROVIDER` | Explicit LLM credentials for SDK / CLI mode (not needed when pi's configuration — `~/.pi/agent/auth.json` — supplies the key). On the CLI / agent skill both can also live in `config.env` / `cli.env`. The provider is required alongside the key, or inferred from a `provider/model-id` `PI_RESEARCH_MODEL`. |
 | `STACKEXCHANGE_API_KEY` | Raises the Stack Exchange tool's limit from 300/day to 10,000/day. Obtain at <https://stackapps.com/apps/oauth>. |
 | `GITHUB_TOKEN` | Raises the security tool's GitHub Advisory limit from 60/hr to 5000/hr (any default-scope token). |
 | `NVD_API_KEY` | Raises the security tool's NVD limit ~10× and tightens request spacing. Request at <https://nvd.nist.gov/developers/request-an-api-key>. Recommended when using severity-filtered security searches: those issue a second (CVSS v2) NVD query to catch v2-only CVEs, which roughly doubles request time against the 6 s/request unauthenticated throttle. |

package/docs/SDK.md

@@ -13,6 +13,13 @@ run the `pi` extension, which keeps its own private copy your scripts can't impo
 npm install @lincoln504/pi-research
 ```
 
+Then pick the model: pass `model` to `initResearchSDK`, or set `PI_RESEARCH_MODEL`
+(env or `~/.pi/research/config.env`). The SDK never follows the model selected
+inside the pi extension; only when neither is set does it fall back to the first
+available model in your pi registry. The API key comes from your pi
+configuration (`~/.pi/agent/auth.json`) automatically, or from the `apiKey`
+option / `PI_RESEARCH_API_KEY` env var.
+
 `src/sdk.ts` is a library for scripts, CI, and custom tooling. It is configured
 from code, not from a global overlay file — there is no `sdk.env`. It reads the
 base `~/.pi/research/config.env` as a baseline, and everything is
@@ -83,7 +90,7 @@ extension and the CLI / agent skill do it when `PI_RESEARCH_REPORT_EXPORT_ENABLE
 
 | Option | Description |
 |--------|-------------|
-| `model` | `"provider/id"` string or a `Model` object. Omit to use the first available pi model. |
+| `model` | `"provider/id"` string or a `Model` object. Omit to use the configured `PI_RESEARCH_MODEL`; only when neither is set does the SDK fall back to the first available pi model. |
 | `apiKey` / `provider` | Explicit credentials (provider required with apiKey). |
 | `config` | `Partial<Config>` overrides, applied over the base/defaults. |
 | `ignoreGlobalConfig` | Skip `config.env` entirely — defaults + `process.env` + `config` only. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
   "type": "module",
   "private": false,

package/skills/pi-research/README.md

@@ -39,8 +39,8 @@ model/key is missing.
 ### Prerequisites
 
 - Node.js >= 22.19.0
-- `pi-research` installed somewhere the launcher can find it, and a model +
-  API key configured. See [`references/configuration.md`](references/configuration.md).
+- `pi-research` installed somewhere the launcher can find it, and a configured
+  model (`PI_RESEARCH_MODEL`) + API key. See [`references/configuration.md`](references/configuration.md).
 
 ```bash
 npm install -g @lincoln504/pi-research

package/skills/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 name: pi-research
 description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
 license: MIT
-metadata: { "author": "Lincoln Deen", "version": "1.0.2", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.0.3", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---
 
@@ -91,10 +91,13 @@ On exit 78 the engine prints exact configure locations to stderr — relay verba
 ```
 config file:  ~/.pi/research/config.env
 env vars:     PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
-pi auth:      ~/.pi/agent/auth.json
-pi models:    ~/.pi/agent/models.json
+pi config (keys):    ~/.pi/agent/auth.json   (supplies the API key only)
+pi config (models):  ~/.pi/agent/models.json
 ```
 
+`PI_RESEARCH_MODEL` (a `provider/model-id`) is always required — pi's configuration
+supplies only the key, and the skill never uses the model selected inside the pi extension.
+
 Run `status` for the resolved paths on this machine. Full reference:
 [`references/configuration.md`](references/configuration.md).
 

package/skills/pi-research/references/configuration.md

@@ -1,6 +1,8 @@
 ## Configuration
 
-The skill drives the **pi-research** engine, which needs a model + API key.
+The skill drives the **pi-research** engine, which needs an explicitly configured
+model (`PI_RESEARCH_MODEL`) + API key — it runs only on that configured model and
+never follows the model selected inside the pi extension.
 Run `node "<SKILL_DIR>/scripts/run.mjs" status` to print what's detected and where
 to configure (no research runs).
 
@@ -13,7 +15,8 @@ to configure (no research runs).
    export PI_RESEARCH_MODEL=openai/gpt-4o    # provider/model-id
    ```
 2. **Global config** `~/.pi/research/config.env` (same KEY=VALUE keys; read at startup).
-3. **pi auth** (if you use `pi`): `~/.pi/agent/auth.json` + `~/.pi/agent/models.json`.
+3. **pi configuration** (if you use `pi`): the API key comes from `~/.pi/agent/auth.json`
+   automatically — `PI_RESEARCH_MODEL` must still be set (env or `config.env`).
 
 Real env vars always win. Optional CLI-only overlay `~/.pi/research/cli.env` layers
 over `config.env` for the CLI only. Precedence:
@@ -23,7 +26,7 @@ over `config.env` for the CLI only. Precedence:
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `PI_RESEARCH_MODEL` | session model | Model override for all research sub-tasks. |
+| `PI_RESEARCH_MODEL` | _(required)_ | The `provider/model-id` all research runs on. |
 | `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` | `1` | Default depth (1–3) when `--depth` omitted. |
 | `PI_RESEARCH_MAX_RESEARCHERS` | `3` | Parallel researchers (1–5). |
 | `PI_RESEARCH_TIMEOUT_MS` | `300000` | Per-researcher timeout (180000–1800000). |
@@ -70,7 +73,7 @@ model/key; message lists the fix) · `70` runtime error (network/provider/intern
   `export PI_RESEARCH_BIN=/path/to/pi-research/dist/cli.mjs` (exact CLI entry;
   checked first — also the escape hatch for unusual Windows shim layouts).
 - **"No model or API key" (78 from engine):** set the three env vars (or config /
-  pi auth), then re-run `status`.
+  pi's configuration), then re-run `status`.
 - **Rate limit (70):** provider returned 429 — wait and retry.
 - **GPU/embedding errors:** set `PI_RESEARCH_EMBEDDING_DEVICE=cpu` (headless/no-GPU).
 

package/skills/pi-research/scripts/run.mjs

@@ -139,10 +139,11 @@ function notInstalled() {
     "    # or, with pi:   pi install npm:@lincoln504/pi-research",
     "    # or point at a copy: export PI_RESEARCH_PATH=/path/to/pi-research",
     "",
-    "After installing, configure a model + API key. Locations:",
+    "After installing, configure the model (PI_RESEARCH_MODEL is required) + API key.",
+    "Locations:",
     `  \u2022 env vars:           PI_RESEARCH_API_KEY / PI_RESEARCH_PROVIDER / PI_RESEARCH_MODEL`,
     `  \u2022 global config file: ${join(home, ".pi", "research", "config.env")}`,
-    `  \u2022 pi auth storage:    ${join(home, ".pi", "agent", "auth.json")}`,
+    `  \u2022 pi config (keys):   ${join(home, ".pi", "agent", "auth.json")}  (supplies the API key only)`,
     "",
     "Run `status` once installed to verify detection.",
     ""

package/src/cli.ts

@@ -196,7 +196,7 @@ export interface ResolvedConfigPaths {
   cliIfaceEnv: string;
   /** Per-interface overlay for the pi extension (~/.pi/research/pi.env). */
   piIfaceEnv: string;
-  /** pi auth storage (~/.pi/agent/auth.json). */
+  /** pi's key file (~/.pi/agent/auth.json), part of pi's configuration. */
   piAuth: string;
   /** pi model definitions (~/.pi/agent/models.json). */
   piModels: string;
@@ -300,9 +300,29 @@ function detectCredentials(): CredentialDetection {
     };
   }
 
-  // --- pi auth storage path --------------------------------------------------
+  // --- pi configuration path (key from auth.json) -----------------------------
   if (piAuthPresent) {
-    // The SDK will resolve a model from the registry (models.json + PI_RESEARCH_MODEL).
+    // Keys come from auth.json, but the MODEL must be configured explicitly:
+    // the standalone CLI / agent skill run only on the configured model — they
+    // never follow the model selected inside the pi extension, and silently
+    // falling back to the registry's first authed entry picks a model nobody
+    // chose. Fail fast here (pre-flight, before any SDK init).
+    if (!model) {
+      return {
+        source: 'pi-config',
+        apiKeyConfigured: true,
+        provider,
+        model,
+        modelFrom,
+        piAuthPresent,
+        piModelsPresent,
+        problem:
+          'pi credentials were found (auth.json), but no research model is configured. ' +
+          'The standalone CLI / agent skill run only on an explicitly configured model — they do not ' +
+          'follow the model selected inside the pi extension. Set PI_RESEARCH_MODEL to a ' +
+          '"provider/model-id" (in the environment, or in config.env / cli.env below).',
+      };
+    }
     return {
       source: 'pi-config',
       apiKeyConfigured: true, // key lives in auth.json; SDK reads it
@@ -342,14 +362,14 @@ function configBlock(det: CredentialDetection, extraNote?: string): string {
   lines.push(`  • base config file:   ${paths.configEnv}`);
   lines.push(`  • cli overlay:        ${paths.cliIfaceEnv}  (optional; overrides base for this CLI / agent skill)`);
   lines.push(`  • env vars:           PI_RESEARCH_API_KEY / PI_RESEARCH_PROVIDER / PI_RESEARCH_MODEL`);
-  lines.push(`  • pi auth storage:    ${paths.piAuth}`);
-  lines.push(`  • pi models:          ${paths.piModels}`);
+  lines.push(`  • pi config (keys):   ${paths.piAuth}`);
+  lines.push(`  • pi config (models): ${paths.piModels}`);
   lines.push('');
   lines.push('Detected:');
   lines.push(`  • credential source:  ${det.source}`);
   lines.push(`  • api key configured: ${det.apiKeyConfigured}`);
-  lines.push(`  • provider:           ${det.provider ?? '(unset)'}`);
-  lines.push(`  • model:              ${det.model ?? '(unset)'}  [from: ${det.modelFrom}]`);
+  lines.push(`  • provider:           ${det.provider ?? '(unset — inferred from a provider/model-id model)'}`);
+  lines.push(`  • model:              ${det.model ? `${det.model}  [from: ${det.modelFrom}]` : '(not set — set PI_RESEARCH_MODEL, required)'}`);
   lines.push(`  • pi auth.json:       ${det.piAuthPresent ? 'present' : 'absent'}`);
   lines.push(`  • pi models.json:     ${det.piModelsPresent ? 'present' : 'absent'}`);
   if (extraNote) lines.push(`  • note:               ${extraNote}`);
@@ -657,12 +677,23 @@ async function cmdSkill(s: NonNullable<ParsedArgs['skill']>): Promise<number> {
     } catch (err) {
       return reportError(err, 'skill install', s.json);
     }
+    // The skill runs only on an explicitly configured model — if none is set yet,
+    // say so right here, at the moment of install (mirrors the TUI install action).
+    const skillModel =
+      process.env['PI_RESEARCH_MODEL'] ?? getConfig(process.cwd(), 'cli').RESEARCH_MODEL;
     if (s.json) {
-      toStdout(pretty({ command: 'skill', action: 'install', dryRun: !!s.dryRun, results }));
+      toStdout(pretty({ command: 'skill', action: 'install', dryRun: !!s.dryRun, results, modelConfigured: Boolean(skillModel) }));
     } else {
       toStdout(`pi-research agent skill — ${s.dryRun ? 'install (dry run)' : 'install'}\n\n`);
       for (const r of results) toStdout(`  ${r.tool.padEnd(10)} ${describeInstall(r)}\n`);
       toStdout(`\nThe skill activates automatically — ask the agent to research something.\n`);
+      if (!skillModel) {
+        toStdout(
+          `\nRequired: set PI_RESEARCH_MODEL=provider/model-id in ${resolvedConfigPaths().configEnv}\n` +
+          `(or as an env var) — the skill runs only on this configured model, not your pi\n` +
+          `session model. Verify with: ${BINARY_NAME} status\n`
+        );
+      }
     }
     return results.some((r) => r.status === 'error') ? EXIT.SOFTWARE : EXIT.OK;
   }
@@ -842,11 +873,15 @@ COMMANDS
 CONFIGURE
   Credentials are resolved in this order (first match wins):
 
-    env vars:     PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
-    cli overlay:  ${p.cliIfaceEnv}   (optional; this CLI / agent skill only)
-    base config:  ${p.configEnv}
-    pi auth:      ${p.piAuth}
-    pi models:    ${p.piModels}
+    env vars:            PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
+    cli overlay:         ${p.cliIfaceEnv}   (optional; this CLI / agent skill only)
+    base config:         ${p.configEnv}
+    pi config (keys):    ${p.piAuth}
+    pi config (models):  ${p.piModels}
+
+  A model is REQUIRED: set PI_RESEARCH_MODEL to a "provider/model-id". This CLI and
+  the agent skill run only on that configured model — they do not follow the model
+  selected inside the pi extension.
 
   The pi extension has its own optional overlay file:
     pi extension: ${p.piIfaceEnv}

package/src/research-config.ts

@@ -23,7 +23,7 @@ import {
 } from '@earendil-works/pi-tui';
 import { setInteractiveTuiActive, initGlobalTuiController } from './tui/tui-controller.ts';
 import { normalizeSessionId } from './orchestration/session-state.ts';
-import { getConfig, saveConfig, resetConfig, getDbDir } from './config.ts';
+import { getConfig, saveConfig, resetConfig, getDbDir, getGlobalEnvFilePath } from './config.ts';
 import { healthRegistry } from './healthcheck/index.ts';
 import { getService, clearService, tryGetServiceContainerFromCtx } from './core/service-registry.ts';
 import { ServiceNames, IKnowledgeStoreService } from './core/service-interfaces.ts';
@@ -648,6 +648,19 @@ async function installSkillAction(ctx: ExtensionContext, pi: ExtensionAPI): Prom
     }
     lines.push('', 'The skill activates automatically — just ask the agent to pi-research something.');
 
+    // The skill runs only on an explicitly configured model (it never follows the
+    // pi session model) — if none is configured yet, say so right here, at the
+    // moment of install, mirroring the CLI's `skill install` output.
+    const skillModel = process.env['PI_RESEARCH_MODEL'] ?? getConfig(ctx.cwd, 'cli').RESEARCH_MODEL;
+    if (!skillModel) {
+      lines.push(
+        '',
+        '**Required:** set `PI_RESEARCH_MODEL=provider/model-id` in ' +
+        `\`${getGlobalEnvFilePath()}\` (or as an env var) — the skill runs only on ` +
+        'this configured model, not your pi session model.'
+      );
+    }
+
     pi.sendMessage({ customType: 'skill-install-result', content: lines.join('\n'), display: true });
     if (ctx.hasUI) {
       if (ok > 0) ctx.ui.notify(`Skill installed for ${ok} coding agent${ok === 1 ? '' : 's'}.`, 'info');

package/src/sdk.ts

@@ -144,17 +144,21 @@ function _removeSignalHandlers(): void {
  * Options for initializing the Research SDK
  */
 export interface ResearchSDKOptions {
-  /** 
+  /**
    * The LLM model to use for coordination, planning, and evaluation.
-   * If a string, it must match "provider/id" (e.g. "openai/gpt-4o").
-   * If omitted, the first available model in pi's configuration will be used.
+   * If a string, it must match "provider/id" (e.g. "openai/gpt-4o"); a Model
+   * object is used as-is. If omitted, the configured RESEARCH_MODEL
+   * (PI_RESEARCH_MODEL / config.env, or the `config` option) is used; only
+   * when neither is set does the SDK fall back to the first available model
+   * in pi's configuration. The SDK never follows the model selected
+   * interactively inside the pi extension.
    */
   model?: string | Model<any>;
   
   /** 
    * Optional explicit API key for the model. 
    * If provided, `provider` must also be set.
-   * If omitted, pi's global auth storage (~/.pi/agent/auth.json) is used.
+   * If omitted, the key from pi's configuration (~/.pi/agent/auth.json) is used.
    */
   apiKey?: string;
 
@@ -232,15 +236,18 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
   globalApiKey = options.apiKey || process.env['PI_RESEARCH_API_KEY'];
   let parsedProvider = options.provider || process.env['PI_RESEARCH_PROVIDER'];
 
-  // Infer provider from model if not explicitly provided
-  if (!parsedProvider && options.model) {
-    if (typeof options.model === 'string') {
-      const slashIdx = options.model.indexOf('/');
+  // Infer provider from the effective model if not explicitly provided. The
+  // effective model is the explicit option first, else the configured
+  // RESEARCH_MODEL — the same precedence the resolve below uses.
+  const effectiveModel = options.model ?? globalConfig.RESEARCH_MODEL;
+  if (!parsedProvider && effectiveModel) {
+    if (typeof effectiveModel === 'string') {
+      const slashIdx = effectiveModel.indexOf('/');
       if (slashIdx > 0) {
-        parsedProvider = options.model.slice(0, slashIdx);
+        parsedProvider = effectiveModel.slice(0, slashIdx);
       }
-    } else if ((options.model as any).provider) {
-      parsedProvider = (options.model as any).provider;
+    } else if ((effectiveModel as any).provider) {
+      parsedProvider = (effectiveModel as any).provider;
     }
   }
 
@@ -252,8 +259,23 @@ async function _doInit(options: ResearchSDKOptions = {}): Promise<void> {
   globalRegistry = sharedBuildModelRegistry(globalApiKey, parsedProvider);
 
   try {
-    // Resolve model using unified logic.
-    globalModel = resolveModel(globalRegistry, typeof options.model === 'string' ? options.model : undefined, parsedProvider, globalApiKey);
+    // Resolve the model. Precedence: explicit option (a Model object is used
+    // as-is; it need not exist in the registry) → configured RESEARCH_MODEL →
+    // provider default → registry fallback. Seeding the resolver with the
+    // configured model is what keeps the coordinator (which runs on ctx.model)
+    // on the SAME model as the researchers/synthesis (which read
+    // RESEARCH_MODEL themselves) — without it a configured model would govern
+    // only the sub-agents and planning would silently run on the fallback.
+    if (effectiveModel && typeof effectiveModel === 'object' && (effectiveModel as any).id) {
+      globalModel = effectiveModel as Model<any>;
+    } else {
+      globalModel = resolveModel(
+        globalRegistry,
+        typeof effectiveModel === 'string' ? effectiveModel : undefined,
+        parsedProvider,
+        globalApiKey
+      );
+    }
 
     // Use the global container to ensure internal services can resolve dependencies
     globalContainer = getServiceContainer();