pi-ui-extend 0.1.72 → 0.1.77

package/README.md

@@ -22,7 +22,7 @@ npx pi-ui-extend install
 npx pi-ui-extend --cwd .
 ```
 
-The setup command checks the icon font, the `pi` CLI, and clipboard support. The second command opens the current project in Pix without requiring a global Pix install.
+The setup command checks runtime helpers, creates non-secret Pix and tools configuration templates when missing, and prints a credential-aware checklist. It never imports credentials. The second command opens the current project in Pix without requiring a global Pix install.
 
 > Already installed globally? Run `pix --cwd .`.
 
@@ -152,6 +152,19 @@ npx pi-ui-extend install
 npx pi-ui-extend --cwd /path/to/project
 ```
 
+### First-run checklist
+
+1. Run `npx pi-ui-extend install`. It preserves existing files and creates these non-secret templates when missing:
+   - `~/.config/pi/pix.jsonc`
+   - `~/.config/pi/pi-tools-suite.jsonc`
+2. Configure at least one model provider:
+   - With an existing OpenCode setup, start Pix and run `/opencode-import`; review [OpenCode migration](#opencode-migration) before using `--force`.
+   - Otherwise run `npx @earendil-works/pi-coding-agent`, use `/login` in the stock Pi TUI, then exit. Environment-based provider API keys also work.
+3. Start Pix, use `/model` to select an available model, and follow any startup authentication diagnostic.
+4. Configure only the optional integrations you need; none are required for normal model conversations.
+
+The installer installs JetBrainsMono Nerd Font when it is missing. Pix also checks it on startup and starts a background installation when needed so the icon UI remains readable even when setup was skipped. Installation failures are reported while Pix keeps its fallback icons. Use `--check` to inspect the machine without creating files, installing helpers, or changing credentials.
+
 ### Global install
 
 ```bash
@@ -190,8 +203,37 @@ pix --cwd . --no-session
 
 Pix uses Pi's model and authentication stores. Environment-based API keys and credentials already configured for Pi are available to Pix.
 
-- Run the stock `pi` TUI when you need its provider login/logout dialogs, then use `/reload` in Pix.
-- Run `/opencode-import` to import supported credentials from OpenCode.
+| Credential or integration | Required? | Setup | Notes |
+| --- | --- | --- | --- |
+| Model provider | **Yes**, unless the selected model needs no credentials | Run the stock Pi TUI with `npx @earendil-works/pi-coding-agent`, use `/login`, then `/reload` in Pix; or set a provider-supported environment key | Pix does not yet implement Pi's interactive `/login` and `/logout` dialogs. |
+| Existing OpenCode accounts | No; migration shortcut | Run `/opencode-import` in Pix | Imports only the credential types listed below and preserves existing Pi entries by default. |
+| Model-backed helpers | No | Review `promptEnhancer`, `autocomplete`, and `sessionTitle` in `pix.jsonc` | Each configured helper model needs credentials for its own provider; it need not use the main session provider. |
+| Ollama/Tavily web access | No | Use local Ollama without a cloud key, set `OLLAMA_API_KEY`/`TAVILY_API_KEY`, or run `/web-credentials` | Stored keys live in `~/.config/pi/pi-tools-suite-credentials.json` with mode `0600`. |
+| Context7 documentation skill | No | Export `CONTEXT7_API_KEY` | The skill fails before making a network request when the variable is absent. |
+| Telegram terminal bell | No | Configure `terminalBell.telegram` or `PI_TERMINAL_BELL_TELEGRAM_BOT_TOKEN` plus `PI_TERMINAL_BELL_TELEGRAM_CHAT_ID` | Used only for the optional terminal notification integration. |
+
+`pix install` reports whether these sources appear configured, but never displays, copies, or overwrites token values.
+
+### OpenCode migration
+
+Run this inside Pix after the bundled tools suite loads:
+
+```text
+/opencode-import
+```
+
+Supported mappings are deliberately narrow:
+
+- OpenAI OAuth → Pi's `openai-codex` provider
+- OpenAI API key → Pi's `openai` provider
+- GitHub Copilot OAuth → `github-copilot`
+- Z.ai/Zhipu-compatible credentials → `zai`
+- an OpenCode Antigravity account → Pi's Antigravity provider
+
+By default the command reads `$OPENCODE_AUTH_CONTENT`, `$OPENCODE_DATA_DIR/auth.json`, or the XDG/default OpenCode data path, plus the corresponding OpenCode Antigravity account file. It writes to Pi's active agent directory (`$PI_CODING_AGENT_DIR` when set), preserves existing provider entries, and reloads Pix only after a successful write. Use `/opencode-import --force` only when you intentionally want supported existing entries replaced. Explicit source and destination paths are available through `/opencode-import --path <file>`, `--auth-path <file>`, and `--antigravity-path <file>`.
+
+OpenCode model/provider definitions, default-model choices, MCP servers, plugins, instructions, and tool settings are **not** migrated because their formats and security assumptions do not map safely. Recreate those settings in Pix/Pi and `pi-tools-suite.jsonc` as needed. No secret is imported during `pix install` itself.
+
 - Run `/antigravity-add-account` to add an Antigravity OAuth account, then use `/antigravity-account` and `/antigravity-status` to manage it.
 - Use `/model`, `/scoped-models`, and `/thinking` to control the active runtime.
 - Use `/default-model`, `/default-thinking`, and `/autocomplete` to change defaults for new sessions.

package/dist/app/cli/install.d.ts

@@ -1,9 +1,12 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { installJetBrainsNerdFont, isJetBrainsNerdFontInstalled } from "../terminal/nerd-font-controller.js";
 import { clipboardInstallHint, clipboardSupportAvailable } from "../screen/clipboard.js";
 type PixInstallTestDeps = {
     existsSync: typeof existsSync;
+    readFileSync: typeof readFileSync;
+    mkdirSync: typeof mkdirSync;
+    writeFileSync: typeof writeFileSync;
     spawn: typeof spawn;
     isJetBrainsNerdFontInstalled: typeof isJetBrainsNerdFontInstalled;
     installJetBrainsNerdFont: typeof installJetBrainsNerdFont;
@@ -19,7 +22,22 @@ export type PixInstallCliContext = {
     env?: NodeJS.ProcessEnv;
     homeDir?: string;
 };
-export declare function formatPixInstallNextSteps(homeDir?: string): string;
+export type PixOnboardingState = {
+    pixConfigExists: boolean;
+    toolsConfigExists: boolean;
+    providerAuthConfigured: boolean;
+    opencodeAuthExists: boolean;
+    opencodeAntigravityExists: boolean;
+    webCredentialsConfigured: boolean;
+    context7Configured: boolean;
+    telegramConfigured: boolean;
+};
+export declare function inspectPixOnboarding(homeDir?: string, env?: NodeJS.ProcessEnv): PixOnboardingState;
+export declare function ensurePixSetupFiles(homeDir?: string): {
+    created: string[];
+    existing: string[];
+};
+export declare function formatPixInstallNextSteps(homeDir?: string, state?: PixOnboardingState): string;
 export declare function pixInstallUsage(): string;
 export declare function parsePixInstallArgs(argv: readonly string[]): PixInstallCliOptions;
 export declare function runPixInstallCli(argv?: readonly string[], context?: PixInstallCliContext): Promise<number>;

package/dist/app/cli/install.js

@@ -1,12 +1,16 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { FONT_FAMILY_NAME, installJetBrainsNerdFont, isJetBrainsNerdFontInstalled, } from "../terminal/nerd-font-controller.js";
 import { clipboardInstallHint, clipboardSupportAvailable } from "../screen/clipboard.js";
 import { getPixConfigPath } from "../../config.js";
+import { DEFAULT_PIX_CONFIG_JSONC } from "../../default-pix-config.js";
 const defaultPixInstallDeps = {
     existsSync,
+    readFileSync,
+    mkdirSync,
+    writeFileSync,
     spawn,
     isJetBrainsNerdFontInstalled,
     installJetBrainsNerdFont,
@@ -17,24 +21,114 @@ let pixInstallDeps = defaultPixInstallDeps;
 export function setPixInstallTestDeps(overrides) {
     pixInstallDeps = overrides ? { ...defaultPixInstallDeps, ...overrides } : defaultPixInstallDeps;
 }
-export function formatPixInstallNextSteps(homeDir = homedir()) {
+const PROVIDER_API_KEY_ENV_NAMES = [
+    "ANTHROPIC_API_KEY",
+    "AZURE_OPENAI_API_KEY",
+    "GEMINI_API_KEY",
+    "GOOGLE_API_KEY",
+    "GROQ_API_KEY",
+    "MISTRAL_API_KEY",
+    "OPENAI_API_KEY",
+    "OPENROUTER_API_KEY",
+    "XAI_API_KEY",
+    "ZAI_API_KEY",
+];
+const DEFAULT_TOOLS_CONFIG_JSONC = `{
+  "$schema": "https://unpkg.com/pi-ui-extend/schemas/pi-tools-suite.json",
+  "todoThinking": true,
+  "disabledModules": []
+}
+`;
+export function inspectPixOnboarding(homeDir = homedir(), env = process.env) {
+    const pixConfigPath = getPixConfigPath(homeDir);
+    const toolsConfigPath = join(homeDir, ".config", "pi", "pi-tools-suite.jsonc");
+    const agentDir = env.PI_CODING_AGENT_DIR?.trim() || join(homeDir, ".pi", "agent");
+    const piAuthPath = join(agentDir, "auth.json");
+    const opencodeDataDir = env.OPENCODE_DATA_DIR?.trim()
+        || join(env.XDG_DATA_HOME?.trim() || join(homeDir, ".local", "share"), "opencode");
+    const opencodeConfigDir = env.OPENCODE_CONFIG_DIR?.trim()
+        || join(env.XDG_CONFIG_HOME?.trim() || join(homeDir, ".config"), "opencode");
+    const webCredentialPath = env.PI_TOOLS_SUITE_WEB_CREDENTIALS_PATH?.trim()
+        || join(homeDir, ".config", "pi", "pi-tools-suite-credentials.json");
+    const providerEnvConfigured = PROVIDER_API_KEY_ENV_NAMES.some((name) => Boolean(env[name]?.trim()));
+    return {
+        pixConfigExists: pixInstallDeps.existsSync(pixConfigPath),
+        toolsConfigExists: pixInstallDeps.existsSync(toolsConfigPath),
+        providerAuthConfigured: providerEnvConfigured || jsonObjectHasEntries(piAuthPath),
+        opencodeAuthExists: Boolean(env.OPENCODE_AUTH_CONTENT?.trim()) || pixInstallDeps.existsSync(join(opencodeDataDir, "auth.json")),
+        opencodeAntigravityExists: pixInstallDeps.existsSync(join(opencodeConfigDir, "antigravity-accounts.json")),
+        webCredentialsConfigured: Boolean(env.OLLAMA_API_KEY?.trim() || env.TAVILY_API_KEY?.trim()) || jsonObjectHasEntries(webCredentialPath),
+        context7Configured: Boolean(env.CONTEXT7_API_KEY?.trim()),
+        telegramConfigured: Boolean(env.PI_TERMINAL_BELL_TELEGRAM_BOT_TOKEN?.trim() && env.PI_TERMINAL_BELL_TELEGRAM_CHAT_ID?.trim()),
+    };
+}
+export function ensurePixSetupFiles(homeDir = homedir()) {
+    const files = [
+        { path: getPixConfigPath(homeDir), content: DEFAULT_PIX_CONFIG_JSONC },
+        { path: join(homeDir, ".config", "pi", "pi-tools-suite.jsonc"), content: DEFAULT_TOOLS_CONFIG_JSONC },
+    ];
+    const created = [];
+    const existing = [];
+    for (const file of files) {
+        if (pixInstallDeps.existsSync(file.path)) {
+            existing.push(file.path);
+            continue;
+        }
+        pixInstallDeps.mkdirSync(dirname(file.path), { recursive: true });
+        try {
+            pixInstallDeps.writeFileSync(file.path, file.content, { encoding: "utf8", flag: "wx" });
+            created.push(file.path);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            existing.push(file.path);
+        }
+    }
+    return { created, existing };
+}
+export function formatPixInstallNextSteps(homeDir = homedir(), state = inspectPixOnboarding(homeDir)) {
     const pixConfigPath = getPixConfigPath(homeDir);
     const toolsConfigPath = join(homeDir, ".config", "pi", "pi-tools-suite.jsonc");
+    const opencodeDetected = state.opencodeAuthExists || state.opencodeAntigravityExists;
+    const providerStep = formatProviderSetupStep(state.providerAuthConfigured, opencodeDetected);
     return [
         "",
-        "Next steps:",
-        `  1. Edit ${pixConfigPath} and set dictation.language / dictation.languages for voice input.`,
-        `  2. Edit ${toolsConfigPath} and enable the LSP servers you use under lsp.servers.`,
-        "  3. Start pix, then run /opencode-import to import opencode accounts.",
-        "     For Antigravity accounts, run /antigravity-import or /antigravity-add-account.",
+        "First-run setup:",
+        providerStep,
+        ...(opencodeDetected ? [
+            "    /opencode-import safely preserves existing Pi credentials unless --force is used.",
+            "    Supported migration: OpenAI/Codex, GitHub Copilot, Z.ai, and Antigravity credentials; OpenCode models, MCP, plugins, and tool settings are reported as manual work.",
+        ] : []),
+        `  ${state.pixConfigExists ? "✓" : "→"} Pix config: ${pixConfigPath}`,
+        `  ${state.toolsConfigExists ? "✓" : "→"} Tools config: ${toolsConfigPath}`,
+        "",
+        "Optional integrations:",
+        `  ${state.webCredentialsConfigured ? "✓ Web credentials detected." : "○ Web search: use local Ollama without a key, or run /web-credentials for Ollama Cloud/Tavily."}`,
+        `  ${state.context7Configured ? "✓ Context7 API key detected." : "○ Context7 docs skill: export CONTEXT7_API_KEY."}`,
+        `  ${state.telegramConfigured ? "✓ Telegram terminal-bell credentials detected in the environment." : "○ Telegram bell: set terminalBell.telegram in Pix config or PI_TERMINAL_BELL_TELEGRAM_* env vars."}`,
+        "  ○ Model-backed helpers: review promptEnhancer, autocomplete, and sessionTitle model refs; each provider needs its own credentials.",
+        "  ○ Voice: set dictation.language in Pix config. LSP: configure and trust servers under lsp.servers in tools config.",
+        "",
+        "Pix never imports or overwrites credentials during install. Optional tokens remain opt-in.",
     ].join("\n");
 }
+function formatProviderSetupStep(providerAuthConfigured, opencodeDetected) {
+    if (providerAuthConfigured)
+        return "  ✓ Model provider credentials detected. Start Pix and use /model to choose a model.";
+    if (opencodeDetected)
+        return "  → OpenCode credentials detected. Start Pix, run /opencode-import, then /model.";
+    return "  → Configure a model provider first: run `npx @earendil-works/pi-coding-agent`, use /login, then start Pix and use /model.";
+}
 export function pixInstallUsage() {
     return `Usage: pix install [--check]
        pix setup [--check]
 
 Check and install Pix runtime helpers for this user.
 
+It also creates non-secret Pix and pi-tools-suite config templates and prints a
+credential-aware first-run checklist. It never imports credentials automatically.
+
 What it checks:
   - ${FONT_FAMILY_NAME} icon font for Pix glyphs
   - pi CLI availability, including Pix's bundled Pi dependency
@@ -81,7 +175,6 @@ export async function runPixInstallCli(argv = process.argv.slice(2), context = {
     }
     else if (options.checkOnly) {
         console.log(`! ${FONT_FAMILY_NAME} is missing`);
-        failures += 1;
     }
     else {
         try {
@@ -89,8 +182,7 @@ export async function runPixInstallCli(argv = process.argv.slice(2), context = {
             console.log(`✓ Installed ${FONT_FAMILY_NAME}`);
         }
         catch (error) {
-            console.error(`✗ Failed to install ${FONT_FAMILY_NAME}: ${errorMessage(error)}`);
-            failures += 1;
+            console.warn(`! Failed to install optional ${FONT_FAMILY_NAME}: ${errorMessage(error)}`);
         }
     }
     const piCli = await resolvePiCliStatus(env);
@@ -117,12 +209,35 @@ export async function runPixInstallCli(argv = process.argv.slice(2), context = {
     }
     else {
         console.log(`! Clipboard support is missing. ${pixInstallDeps.clipboardInstallHint()}`);
-        if (process.platform === "linux")
+    }
+    const homeDir = context.homeDir ?? homedir();
+    if (!options.checkOnly) {
+        try {
+            const setupFiles = ensurePixSetupFiles(homeDir);
+            for (const path of setupFiles.created)
+                console.log(`✓ Created ${path}`);
+            for (const path of setupFiles.existing)
+                console.log(`✓ Kept existing ${path}`);
+        }
+        catch (error) {
+            console.error(`✗ Failed to create setup config: ${errorMessage(error)}`);
             failures += 1;
+        }
     }
-    console.log(formatPixInstallNextSteps(context.homeDir));
+    console.log(formatPixInstallNextSteps(homeDir, inspectPixOnboarding(homeDir, env)));
     return failures === 0 ? 0 : 1;
 }
+function jsonObjectHasEntries(path) {
+    if (!pixInstallDeps.existsSync(path))
+        return false;
+    try {
+        const parsed = JSON.parse(pixInstallDeps.readFileSync(path, "utf8"));
+        return parsed !== null && typeof parsed === "object" && !Array.isArray(parsed) && Object.keys(parsed).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
 async function resolvePiCliStatus(env) {
     const bundledBin = env.PIX_BUNDLED_PI_BIN;
     if (bundledBin && (pixInstallDeps.existsSync(join(bundledBin, process.platform === "win32" ? "pi.cmd" : "pi")) || pixInstallDeps.existsSync(join(bundledBin, "pi")))) {

package/dist/app/cli/startup-checks.d.ts

@@ -4,5 +4,6 @@ export type StartupAvailabilityIssue = {
     message: string;
 };
 export declare function collectStartupAvailabilityIssues(runtime: AgentSessionRuntime): Promise<StartupAvailabilityIssue[]>;
+export declare function checkSelectedModelAuthAvailability(runtime: AgentSessionRuntime): StartupAvailabilityIssue[];
 export declare function checkPiCliAvailability(pathValue?: string): Promise<StartupAvailabilityIssue[]>;
 export declare function checkPiToolsSuiteExtensionAvailability(extensionsResult: LoadExtensionsResult): StartupAvailabilityIssue[];

package/dist/app/cli/startup-checks.js

@@ -7,8 +7,24 @@ export async function collectStartupAvailabilityIssues(runtime) {
     return [
         ...(await checkPiCliAvailability()),
         ...checkPiToolsSuiteExtensionAvailability(runtime.services.resourceLoader.getExtensions()),
+        ...checkSelectedModelAuthAvailability(runtime),
     ];
 }
+export function checkSelectedModelAuthAvailability(runtime) {
+    const model = runtime.session.model;
+    if (!model) {
+        return [{
+                kind: "error",
+                message: "No model is selected. Configure a provider with `npx @earendil-works/pi-coding-agent` and /login (or run /opencode-import), then choose /model in Pix.",
+            }];
+    }
+    if (runtime.services.modelRuntime.getProviderAuthStatus(model.provider).configured)
+        return [];
+    return [{
+            kind: "error",
+            message: `Selected model ${model.provider}/${model.id} has no configured credentials. Use \`npx @earendil-works/pi-coding-agent\` and /login, or run /opencode-import for supported OpenCode accounts, then choose /model.`,
+        }];
+}
 export async function checkPiCliAvailability(pathValue = process.env.PATH ?? "") {
     if (await executableExistsOnPath(PI_CLI_COMMAND, pathValue))
         return [];

package/dist/app/commands/command-model-actions.js

@@ -67,7 +67,7 @@ export class ModelCommandActions {
         const parsed = parseScopedModelRef(modelRef);
         if (!parsed)
             throw new Error("Model must use provider/model[:thinking] format");
-        await runtime.services.modelRuntime.reloadConfig();
+        await runtime.services.modelRuntime.refresh();
         if (!isCommandScopeActive(this.host, scope))
             return;
         const model = runtime.services.modelRuntime.getModel(parsed.provider, parsed.modelId);
@@ -108,7 +108,7 @@ export class ModelCommandActions {
         const parsed = parseScopedModelRef(modelRef);
         if (!parsed)
             throw new Error("Model must use provider/model[:thinking] format");
-        await runtime.services.modelRuntime.reloadConfig();
+        await runtime.services.modelRuntime.refresh();
         if (!isCommandScopeActive(this.host, scope))
             return;
         const model = runtime.services.modelRuntime.getModel(parsed.provider, parsed.modelId);
@@ -132,7 +132,7 @@ export class ModelCommandActions {
         const parsed = parseScopedModelRef(modelRef);
         if (!parsed)
             throw new Error("Model must use provider/model[:thinking] format, or run /autocomplete with no arguments to disable");
-        await runtime.services.modelRuntime.reloadConfig();
+        await runtime.services.modelRuntime.refresh();
         if (!isCommandScopeActive(this.host, scope))
             return;
         const model = runtime.services.modelRuntime.getModel(parsed.provider, parsed.modelId);
@@ -216,7 +216,7 @@ export class ModelCommandActions {
         const refs = value.split(/[,\s]+/).map((ref) => ref.trim()).filter(Boolean);
         const scopedModels = [];
         const invalidRefs = [];
-        await runtime.services.modelRuntime.reloadConfig();
+        await runtime.services.modelRuntime.refresh();
         if (!isCommandScopeActive(this.host, scope))
             return;
         for (const ref of refs) {

package/dist/app/input/autocomplete-controller.js

@@ -142,7 +142,7 @@ export async function completeInputWithPi(runtime, draft, config, signal) {
     const modelRuntime = runtime.services.modelRuntime;
     let model = modelRuntime.getModel(parsedModel.provider, parsedModel.modelId);
     if (!model) {
-        await modelRuntime.reloadConfig();
+        await modelRuntime.refresh();
         model = modelRuntime.getModel(parsedModel.provider, parsedModel.modelId);
     }
     if (!model)

package/dist/app/input/prompt-enhancer-controller.js

@@ -144,7 +144,7 @@ async function enhancePromptWithPi(runtime, draft, config) {
             systemPrompt: PROMPT_ENHANCER_SYSTEM_PROMPT,
         },
     });
-    await services.modelRuntime.reloadConfig();
+    await services.modelRuntime.refresh();
     const model = services.modelRuntime.getModel(parsedModel.provider, parsedModel.modelId);
     if (!model) {
         throw new Error(modelNotFoundMessage(parsedModel.provider, parsedModel.modelId, services.modelRuntime.getModels()));

package/dist/app/runtime.d.ts

@@ -12,11 +12,13 @@ export type PiToolsSuiteInstallOptions = {
     sourcePath?: string;
     targetPath?: string;
 };
-export type BundledSkillsInstallAction = "installed" | "already-installed" | "missing-source";
+export type BundledSkillsInstallAction = "installed" | "already-installed" | "existing-kept" | "missing-source";
 export type BundledSkillsInstallResult = {
     action: BundledSkillsInstallAction;
     sourcePath: string;
     targetPath: string;
+    installedSkills: string[];
+    preservedSkills: string[];
 };
 export type BundledSkillsInstallOptions = {
     homeDir?: string;

package/dist/app/runtime.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { access, cp, lstat, mkdir, readlink, realpath, rm, symlink } from "node:fs/promises";
+import { access, cp, lstat, mkdir, readdir, readlink, realpath, rm, symlink } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -68,14 +68,31 @@ export async function ensureBundledSkillsInstalled(options = {}) {
     const targetPath = resolve(options.targetPath ?? bundledSkillsInstallPath(options.homeDir));
     const sourceStat = await lstat(sourcePath).catch(() => undefined);
     if (!sourceStat?.isDirectory()) {
-        return { action: "missing-source", sourcePath, targetPath };
+        return { action: "missing-source", sourcePath, targetPath, installedSkills: [], preservedSkills: [] };
     }
     if (await pathsReferToSameEntry(sourcePath, targetPath)) {
-        return { action: "already-installed", sourcePath, targetPath };
+        return { action: "already-installed", sourcePath, targetPath, installedSkills: [], preservedSkills: [] };
     }
-    await mkdir(dirname(targetPath), { recursive: true });
-    await cp(sourcePath, targetPath, { recursive: true, force: true });
-    return { action: "installed", sourcePath, targetPath };
+    await mkdir(targetPath, { recursive: true });
+    const installedSkills = [];
+    const preservedSkills = [];
+    for (const entry of await readdir(sourcePath, { withFileTypes: true })) {
+        if (!entry.isDirectory())
+            continue;
+        const skillTarget = join(targetPath, entry.name);
+        if (await lstat(skillTarget).catch(() => undefined)) {
+            preservedSkills.push(entry.name);
+            continue;
+        }
+        await cp(join(sourcePath, entry.name), skillTarget, { recursive: true, errorOnExist: true, force: false });
+        installedSkills.push(entry.name);
+    }
+    let action = "already-installed";
+    if (installedSkills.length > 0)
+        action = "installed";
+    else if (preservedSkills.length > 0)
+        action = "existing-kept";
+    return { action, sourcePath, targetPath, installedSkills, preservedSkills };
 }
 export function getBundledExtensionPaths() {
     return [
@@ -239,7 +256,7 @@ export async function createPixRuntime(options, runtimeOptions = {}) {
                 config,
                 ...(runtimeOptions.eventBus === undefined ? {} : { eventBus: runtimeOptions.eventBus }),
             });
-        await services.modelRuntime.reloadConfig();
+        await services.modelRuntime.refresh();
         const model = parsedModel ? services.modelRuntime.getModel(parsedModel.provider, parsedModel.modelId) : undefined;
         if (parsedModel && !model) {
             throw new Error(`Model not found: ${parsedModel.provider}/${parsedModel.modelId}`);

package/external/pi-tools-suite/README.md

@@ -12,17 +12,18 @@ This package keeps shared Pi tools as ordinary source folders under `src/` and r
 - `src/session-name` — `session_name` tool for reading or setting the current session title directly from tool calls, without relying on slash-command parsing
 - `src/repo-discovery` — `/idx-init`, `/idx-update`, and indexed-only `repo_architecture` / `repo_structure` / `repo_ast` / `repo_search` / `repo_explain` / `repo_deps`; tools register only when the launch project has `.indexer-cli`
 - `src/antigravity-auth` — `antigravity` custom provider with Google Antigravity OAuth login, startup account list, auth.json-only runtime account loading, `/antigravity-add-account` OAuth append into rotation, `/antigravity-account` status display, account rotation/failover, Antigravity plus Gemini CLI model registration, and streaming through the Cloud Code Assist unified gateway
+- `src/opencode-import` — `/opencode-import` for bounded migration of supported OpenCode OpenAI/Codex, GitHub Copilot, Z.ai, and Antigravity credentials into Pi; existing entries are preserved unless `--force` is passed
 - `src/todo` — `todo` tool, `/todos`, `/todos-persist`, and `/todos-scope`; supports parent/subtask hierarchy, blockers, ready-task filtering, deferred out-of-scope items, batch operations, JSON/Markdown import/export, automatic clearing when all visible todos are completed, and optional project persistence via `/todos persist on` or `/todos-persist on`; localization/i18n has been removed
 - `src/model-tools` — model-specific tool aliases such as Claude/GLM-style `Read` / `Edit` / `Write` / `Bash` / `Grep` / `Glob` / `LS`, GPT/Codex-style `shell`, and model-gated `apply_patch`
 - `src/usage` — `/usage` command and startup hint for read-only AI quota checks across OpenAI, Zhipu AI, Z.ai, and Google Antigravity, including Antigravity quota by model
-- `src/web-search` — `web_search` and `web_fetch` tools migrated from `@ollama/pi-web-search`; calls the local Ollama experimental web search/fetch APIs, honors `OLLAMA_HOST`, supports request timeouts via `timeout_ms` / `PI_WEB_SEARCH_TIMEOUT_MS`, and reports targeted `ollama signin`, unsupported-endpoint, invalid-response, timeout, DNS, and Ollama-not-running errors
+- `src/web-search` — `web_search` and `web_fetch` tools migrated from `@ollama/pi-web-search`; uses local Ollama by default or the official Ollama cloud API when an API key is configured, supports Tavily Search/Extract fallback, provides `/web-credentials` for secure user-level key storage, honors `OLLAMA_HOST`, supports request timeouts via `timeout_ms` / `PI_WEB_SEARCH_TIMEOUT_MS`, and reports provider-specific errors
 - `src/dcp` — headless Dynamic Context Pruning ported from `opencode-dynamic-context-pruning` for the Pi SDK: explicit `compress` tool with range and message modes, `/dcp` commands (context, stats, sweep, manual, decompress, recompress, compress), same-call overlap validation, recoverable compressed-block rollups, grouped message-mode skip diagnostics, stable raw-message anchors when available, protected user/tool preservation, deduplication, error purging, and context nudges; visualization is left to `compress` tool responses and the renderer-owned context-percent click dialog
 - `src/prompt-commands` — user slash-command builder: `/prompt-commands` opens a CRUD menu for saved prompt-backed slash commands, stores them under `promptCommands` in `~/.config/pi/pi-tools-suite.jsonc`, reloads after edits, and runs each saved prompt as a normal user message
 - `src/skill-installer` — `/install-skill [name]` installs a personal skill folder from `~/.agents/local_skills` into the current project's `.pi/skills/` so it activates as a project-local skill, then automatically runs `/reload` so the new skill is picked up without a manual step; `/export-skill [name]` does the reverse, copying a project-local skill back to `~/.agents/local_skills/` for reuse in other projects (no reload, since the library lives outside the project); with no argument either command shows an interactive menu of available skills (folders containing `SKILL.md`), and the `<name>` form installs/exports it directly (headless-safe); existing destinations prompt to overwrite in the UI and are refused in headless mode; `.DS_Store` files are skipped
 
 `index.ts` is intentionally only a thin auto-discovery shim that re-exports `src/index.ts`. There is no `pi.extensions` manifest here, so local Pi auto-discovery loads the suite once via `~/.pi/agent/extensions/pi-tools-suite/index.ts` and does not double-register tools.
 
-Registration order is preserved in `src/index.ts`: coding-discipline, ast-grep, async-subagents, lsp, comment-checker, session-name, repo-discovery command/tool gate, antigravity-auth provider, todo, model-tools, usage, web-search, dcp, prompt-commands, then skill-installer. Tool metadata and active model-specific tool sets have two modes: standard and repo-aware. When `.indexer-cli` enables `repo_*`, those tools stay active ahead of overlapping lower-level aliases so the indexed discovery surface has priority.
+Registration order is preserved in `src/index.ts`: coding-discipline, ast-grep, async-subagents, lsp, comment-checker, session-name, repo-discovery command/tool gate, antigravity-auth provider, OpenCode import, todo, model-tools, usage, web-search, dcp, prompt-commands, then skill-installer. Tool metadata and active model-specific tool sets have two modes: standard and repo-aware. When `.indexer-cli` enables `repo_*`, those tools stay active ahead of overlapping lower-level aliases so the indexed discovery surface has priority.
 
 ## Disabling modules
 
@@ -303,24 +304,57 @@ Runtime logs are minimized by default: successful agents do not keep `events.jso
 
 `asyncSubagents` config also supports `maxConcurrent` (default 5, project-wide; `0` means unlimited), global/per-type `retry` with exponential backoff, global/per-type `maxResultBytes` for bounding `result.json.resultText` while keeping raw `result.md` intact, and global/per-type/preset `timeoutMs` for wall-clock agent watchdogs. Spawn calls and individual task objects can pass `timeoutSeconds` to shorten the watchdog for synthetic tests or bounded probes. Stop requests mark running, queued planned, and retry-pending agents as `stopped` so queued work is not launched later. Completed agents write `result.json` with status/duration/model/retry metadata plus best-effort `summary`, `findings`, `files`, `risks`, `nextActions`, and `confidence` fields for parent-agent chaining.
 
+## OpenCode credential import
+
+`/opencode-import` migrates only credential formats with an explicit Pi mapping: OpenAI OAuth to `openai-codex`, OpenAI API keys to `openai`, GitHub Copilot OAuth, Z.ai aliases, and one matching OpenCode Antigravity account. It does not migrate OpenCode model definitions, defaults, MCP servers, plugins, instructions, or tool settings.
+
+The default source is `OPENCODE_AUTH_CONTENT`, `OPENCODE_DATA_DIR/auth.json`, or the XDG/default OpenCode data directory. The destination is the active Pi agent directory, including `PI_CODING_AGENT_DIR`. Existing Pi credentials are preserved; pass `--force` only to replace supported entries intentionally. Successful writes are atomic, use restrictive file permissions, and trigger a runtime reload. The command also accepts `--path`, `--auth-path`, `--antigravity-path`, `--skip-auth-json`, and `--skip-antigravity` for controlled migrations.
+
 ## Web search
 
-`src/web-search` registers two Ollama-backed tools:
+`src/web-search` registers two Ollama-first tools and the `/web-credentials` setup command:
+
+- `web_search` posts `{ query, max_results }` and returns formatted title/URL/snippet results plus structured `details.results`.
+- `web_fetch` posts `{ url }` and returns extracted page text plus title/link metadata.
+- `/web-credentials` can set, inspect, or clear stored Ollama and Tavily API keys. Notifications and status output never display key values.
+
+Without an Ollama API key, both tools default to `http://localhost:11434/api/experimental/...`; set `OLLAMA_HOST` to point at another Ollama instance. With an Ollama API key and no explicit `OLLAMA_HOST`, they use the official `https://ollama.com/api/web_search` and `/api/web_fetch` endpoints with bearer authentication. Requests time out after 30 seconds by default. Override globally with `PI_WEB_SEARCH_TIMEOUT_MS` or per call with `timeout_ms` (maximum 120000 ms). Tool results include `host`, `timeoutMs`, and truncation metadata in `details`.
+
+Configure a Tavily key to enable automatic fallback for both tools. Ollama remains the primary provider; if any Ollama request or response fails, `web_search` retries through `https://api.tavily.com/search` and `web_fetch` retries through `https://api.tavily.com/extract`. The Tavily key is sent only in Tavily's bearer authorization header and is never accepted as a tool parameter or included in result details. Fallback results set `details.provider` to `tavily` and include the primary Ollama error under `details.fallbackFrom`; ordinary results set `details.provider` to `ollama`.
+
+The recommended interactive setup is:
+
+```text
+/web-credentials
+```
+
+Choose Ollama or Tavily, paste the key, and it becomes active for later calls without a reload. Keys are stored in `~/.config/pi/pi-tools-suite-credentials.json` with mode `0600`. The same command can show configuration sources or clear stored keys without displaying them.
+
+The command displays the official key pages before opening its menu:
 
-- `web_search` posts `{ query, max_results }` to `/api/experimental/web_search` and returns formatted title/URL/snippet results plus structured `details.results`.
-- `web_fetch` posts `{ url }` to `/api/experimental/web_fetch` and returns extracted page text plus title/link metadata.
+- Ollama: <https://ollama.com/settings/keys>
+- Tavily: <https://app.tavily.com/home>
+
+Environment variables remain supported and take precedence over stored keys:
+
+```bash
+export OLLAMA_API_KEY="..."
+export TAVILY_API_KEY="tvly-..."
+```
 
-Both tools default to `http://localhost:11434`; set `OLLAMA_HOST` to point at another Ollama instance. Requests time out after 30 seconds by default. Override globally with `PI_WEB_SEARCH_TIMEOUT_MS` or per call with `timeout_ms` (maximum 120000 ms). Tool results include `host`, `timeoutMs`, and truncation metadata in `details`.
+The timeout applies independently to each provider attempt, so a failed Ollama request followed by Tavily can take up to roughly twice the configured timeout. Tavily Search fallback uses basic search and clamps `max_results` to Tavily's documented maximum of 20. Tavily Extract does not return page title/link metadata, so fallback uses the requested URL as the title and reports no links.
 
 Troubleshooting:
 
 | Symptom | Fix |
 | --- | --- |
 | `Could not connect to Ollama` | Start Ollama and check `OLLAMA_HOST`. |
-| `Unauthorized by Ollama ... Run ollama signin` | Run `ollama signin`, then retry. |
+| `Unauthorized by Ollama` | Run `ollama signin` for local Ollama, or update the Ollama key through `/web-credentials` / `OLLAMA_API_KEY`. |
 | `endpoint is not available` | Update Ollama and make sure the experimental web search/fetch feature is enabled for that install. |
 | `timed out after ...` | Increase per-call `timeout_ms` or `PI_WEB_SEARCH_TIMEOUT_MS` if the local web endpoint is slow. |
 | `invalid JSON` / `unexpected response` | Check the Ollama version and the raw endpoint behavior; the tool reports the bad response shape instead of failing with a generic parser error. |
+| `Tavily ... rejected TAVILY_API_KEY` | Update the Tavily key through `/web-credentials` or `TAVILY_API_KEY`. |
+| `Tavily ... limit was exceeded` | Check Tavily usage/plan limits in the Tavily dashboard. |
 
 Do not send secrets, tokens, private repository text, or credential-bearing URLs through these tools; Ollama may query external web services to satisfy the request.
 

package/external/pi-tools-suite/package.json

@@ -43,9 +43,9 @@
     "vscode-languageserver-protocol": "^3.17.5"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "0.81.1",
-    "@earendil-works/pi-coding-agent": "0.81.1",
-    "@earendil-works/pi-tui": "0.81.1",
+    "@earendil-works/pi-ai": "0.82.1",
+    "@earendil-works/pi-coding-agent": "0.82.1",
+    "@earendil-works/pi-tui": "0.82.1",
     "typebox": "*"
   },
   "devDependencies": {

package/external/pi-tools-suite/src/antigravity-auth/auth-store.ts

@@ -1,10 +1,12 @@
+import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_PROJECT_ID, PROVIDER_ID } from "./constants";
 import type { GoogleOAuthClientCredentials, OpencodeAntigravityAccount, OpencodeAntigravityImportResult, OpencodeAntigravityStorage, PiAuthCredential, PiAuthData } from "./types";
 
-export const PI_AUTH_PATH = join(homedir(), ".pi", "agent", "auth.json");
+export const PI_AUTH_PATH = join(getAgentDir(), "auth.json");
 
 function testPiAuthPath(): string | undefined {
 	return process.env.NODE_ENV === "test" ? process.env.PI_TOOLS_SUITE_TEST_AUTH_PATH : undefined;
@@ -48,7 +50,7 @@ export async function importDefaultOpencodeAntigravityAccount(options: { overwri
 }
 
 export function getPiAuthPath(): string {
-	return testPiAuthPath() ?? PI_AUTH_PATH;
+	return testPiAuthPath() ?? join(getAgentDir(), "auth.json");
 }
 
 export async function readJsonFile<T>(path: string, fallback: T): Promise<T> {
@@ -61,9 +63,21 @@ export async function readJsonFile<T>(path: string, fallback: T): Promise<T> {
 }
 
 export async function writeJsonFileSecure(path: string, data: unknown): Promise<void> {
-	await fs.mkdir(dirname(path), { recursive: true });
-	await fs.writeFile(path, `${JSON.stringify(data, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-	await fs.chmod(path, 0o600).catch(() => undefined);
+	const directory = dirname(path);
+	const temporaryPath = join(directory, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+	await fs.mkdir(directory, { recursive: true });
+	try {
+		await fs.writeFile(temporaryPath, `${JSON.stringify(data, null, 2)}\n`, {
+			encoding: "utf8",
+			flag: "wx",
+			mode: 0o600,
+		});
+		await fs.rename(temporaryPath, path);
+		await fs.chmod(path, 0o600).catch(() => undefined);
+	} catch (error) {
+		await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+		throw error;
+	}
 }
 
 export function getStoredAccounts(credential?: PiAuthCredential): OpencodeAntigravityAccount[] {