pi-ui-extend 0.1.74 → 0.1.78

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/runtime.d.ts

@@ -1,4 +1,4 @@
-import { SessionManager, type EventBus, type AgentSessionRuntime, type LoadExtensionsResult, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import { SessionManager, type EventBus, type AgentSessionRuntime, type AgentSessionServices, type LoadExtensionsResult, type SessionEntry } from "@earendil-works/pi-coding-agent";
 import { type PixConfig } from "../config.js";
 import type { AppOptions, ThinkingLevel } from "./types.js";
 export type PiToolsSuiteInstallAction = "installed" | "already-installed" | "existing-kept" | "missing-source";
@@ -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;
@@ -44,5 +46,6 @@ type RuntimeSessionManagerModelState = Pick<SessionManager, "getEntries" | "getB
 export declare function resolvePixRuntimeModelRef(options: Pick<AppOptions, "modelRef">, sessionManager: RuntimeSessionManagerModelState, config?: PixConfig): string | undefined;
 export declare function resolvePixRuntimeInitialThinkingLevel(options: Pick<AppOptions, "modelRef">, sessionManager: RuntimeSessionManagerModelState, config: PixConfig): ThinkingLevel | undefined;
 export declare function resolveSessionModelRefFromTail(entries: readonly SessionEntry[]): string | undefined;
+export declare function refreshPixModelRuntimeForStartup(modelRuntime: Pick<AgentSessionServices["modelRuntime"], "refresh">): Promise<void>;
 export declare function createPixRuntime(options: AppOptions, runtimeOptions?: CreatePixRuntimeOptions): Promise<AgentSessionRuntime>;
 export {};

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 [
@@ -218,6 +235,11 @@ export function resolveSessionModelRefFromTail(entries) {
         return undefined;
     return thinkingLevel ? `${modelRef}:${thinkingLevel}` : modelRef;
 }
+export async function refreshPixModelRuntimeForStartup(modelRuntime) {
+    // Startup only needs the locally configured model catalog. Remote catalog
+    // refreshes belong to explicit model-management flows and must not block boot.
+    await modelRuntime.refresh({ allowNetwork: false });
+}
 export async function createPixRuntime(options, runtimeOptions = {}) {
     const agentDir = getAgentDir();
     const reusableServices = reusableRuntimeServices(runtimeOptions.reuseServicesFrom, options.cwd, agentDir);
@@ -239,7 +261,7 @@ export async function createPixRuntime(options, runtimeOptions = {}) {
                 config,
                 ...(runtimeOptions.eventBus === undefined ? {} : { eventBus: runtimeOptions.eventBus }),
             });
-        await services.modelRuntime.refresh();
+        await refreshPixModelRuntimeForStartup(services.modelRuntime);
         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,6 +12,7 @@ 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
@@ -22,7 +23,7 @@ This package keeps shared Pi tools as ordinary source folders under `src/` and r
 
 `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,6 +304,12 @@ 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-first tools and the `/web-credentials` setup command:

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[] {

package/external/pi-tools-suite/src/opencode-import/commands.ts

@@ -72,15 +72,18 @@ export function formatOpencodeImportResult(result: OpencodeImportResult): string
 	if (antigravity) providerLines.push(`- ${antigravity}`);
 
 	if (providerLines.length === 0) {
-		return `No opencode credentials were imported. Checked ${result.sourcePath}${result.antigravitySourcePath ? ` and ${result.antigravitySourcePath}` : ""}.`;
+		return `No OpenCode credentials were imported. Checked ${result.sourcePath}${result.antigravitySourcePath ? ` and ${result.antigravitySourcePath}` : ""}.`;
 	}
 
 	const suffix = missingCount > 0 ? `\nMissing ${missingCount} known opencode provider entr${missingCount === 1 ? "y" : "ies"}.` : "";
-	return `Opencode import wrote to ${result.authPath}:\n${providerLines.join("\n")}${suffix}`;
+	const heading = result.wroteAuth ? `Imported OpenCode credentials into ${result.authPath}:` : `OpenCode credential check for ${result.authPath}:`;
+	return `${heading}\n${providerLines.join("\n")}${suffix}`;
 }
 
-export function notificationLevel(result: OpencodeImportResult): "info" | "warn" | "error" {
+export function notificationLevel(result: OpencodeImportResult): "info" | "warning" | "error" {
 	if (result.wroteAuth) return "info";
-	if (result.providers.some((provider) => provider.status === "auth-exists-use-force") || result.antigravity?.reason === "auth-exists-use-force") return "warn";
-	return "error";
+	if (result.providers.some((provider) => provider.status === "auth-exists-use-force") || result.antigravity?.reason === "auth-exists-use-force") return "warning";
+	if (result.providers.some((provider) => provider.status === "invalid-source") || result.antigravity?.reason === "matching-account-not-found") return "error";
+	if (result.providers.some((provider) => provider.status === "already-imported") || result.antigravity?.reason === "already-imported") return "info";
+	return "warning";
 }

package/external/pi-tools-suite/src/opencode-import/importer.ts

@@ -55,16 +55,16 @@ export type OpencodeImportOptions = {
 type Mapping = {
 	label: string;
 	sourceProvider: string;
-	targetProvider: string;
+	targetProvider: string | ((credential: OpencodeAuthCredential | undefined) => string);
 	transform: (credential: OpencodeAuthCredential) => PiAuthCredential | undefined;
 };
 
 const AUTH_JSON_MAPPINGS: Mapping[] = [
 	{
-		label: "OpenAI Codex",
+		label: "OpenAI",
 		sourceProvider: "openai",
-		targetProvider: "openai-codex",
-		transform: transformOAuthCredential,
+		targetProvider: (credential) => (isOAuthCredential(credential) ? "openai-codex" : "openai"),
+		transform: transformOpenAiCredential,
 	},
 	{
 		label: "GitHub Copilot",
@@ -92,24 +92,45 @@ export function getDefaultOpencodeAuthPath(): string {
 }
 
 function transformOAuthCredential(credential: OpencodeAuthCredential): PiAuthCredential | undefined {
-	if (!credential.access && !credential.refresh) return undefined;
+	if (
+		typeof credential.access !== "string" ||
+		!credential.access ||
+		typeof credential.refresh !== "string" ||
+		!credential.refresh ||
+		typeof credential.expires !== "number" ||
+		!Number.isFinite(credential.expires)
+	) {
+		return undefined;
+	}
 	return { ...credential, type: "oauth" };
 }
 
 function transformApiKeyCredential(credential: OpencodeAuthCredential): PiAuthCredential | undefined {
-	if (!credential.key) return undefined;
+	if (typeof credential.key !== "string" || !credential.key) return undefined;
 	return { ...credential, type: "api_key", key: credential.key };
 }
 
+function isOAuthCredential(credential: OpencodeAuthCredential | undefined): boolean {
+	return credential?.type === "oauth" || typeof credential?.access === "string" || typeof credential?.refresh === "string";
+}
+
+function transformOpenAiCredential(credential: OpencodeAuthCredential): PiAuthCredential | undefined {
+	return isOAuthCredential(credential) ? transformOAuthCredential(credential) : transformApiKeyCredential(credential);
+}
+
 function sameCredential(a: PiAuthCredential | undefined, b: PiAuthCredential | undefined): boolean {
 	return JSON.stringify(a ?? null) === JSON.stringify(b ?? null);
 }
 
-function providerResult(mapping: Mapping, status: OpencodeProviderImportStatus): OpencodeProviderImportResult {
+function targetProvider(mapping: Mapping, credential: OpencodeAuthCredential | undefined): string {
+	return typeof mapping.targetProvider === "function" ? mapping.targetProvider(credential) : mapping.targetProvider;
+}
+
+function providerResult(mapping: Mapping, status: OpencodeProviderImportStatus, credential?: OpencodeAuthCredential): OpencodeProviderImportResult {
 	return {
 		label: mapping.label,
 		sourceProvider: mapping.sourceProvider,
-		targetProvider: mapping.targetProvider,
+		targetProvider: targetProvider(mapping, credential),
 		status,
 	};
 }
@@ -123,8 +144,15 @@ async function pathExists(path: string): Promise<boolean> {
 	}
 }
 
+async function readOpencodeAuth(sourcePath: string, environmentSource: string | undefined): Promise<OpencodeAuthData> {
+	if (environmentSource !== undefined) return parseOpencodeAuthContent(environmentSource);
+	if (!(await pathExists(sourcePath))) return {};
+	return readJsonFile<OpencodeAuthData>(sourcePath, {});
+}
+
 export async function importOpencodeAccounts(options: OpencodeImportOptions = {}): Promise<OpencodeImportResult> {
-	const sourcePath = options.sourcePath ?? getDefaultOpencodeAuthPath();
+	const environmentSource = options.sourcePath === undefined ? process.env.OPENCODE_AUTH_CONTENT : undefined;
+	const sourcePath = options.sourcePath ?? (environmentSource !== undefined ? "OPENCODE_AUTH_CONTENT" : getDefaultOpencodeAuthPath());
 	const authPath = options.authPath ?? getPiAuthPath();
 	const result: OpencodeImportResult = {
 		sourcePath,
@@ -138,8 +166,7 @@ export async function importOpencodeAccounts(options: OpencodeImportOptions = {}
 	const changedTargets = new Set<string>();
 
 	if (!options.skipAuthJson) {
-		const sourceExists = await pathExists(sourcePath);
-		const opencodeAuth = sourceExists ? await readJsonFile<OpencodeAuthData>(sourcePath, {}) : {};
+		const opencodeAuth = await readOpencodeAuth(sourcePath, environmentSource);
 
 		for (const mapping of AUTH_JSON_MAPPINGS) {
 			const sourceCredential = opencodeAuth[mapping.sourceProvider];
@@ -147,34 +174,35 @@ export async function importOpencodeAccounts(options: OpencodeImportOptions = {}
 				result.providers.push(providerResult(mapping, "source-missing"));
 				continue;
 			}
+			const resolvedTargetProvider = targetProvider(mapping, sourceCredential);
 
-			if (changedTargets.has(mapping.targetProvider)) {
-				result.providers.push(providerResult(mapping, "target-set-from-other-source"));
+			if (changedTargets.has(resolvedTargetProvider)) {
+				result.providers.push(providerResult(mapping, "target-set-from-other-source", sourceCredential));
 				continue;
 			}
 
 			const nextCredential = mapping.transform(sourceCredential);
 			if (!nextCredential) {
-				result.providers.push(providerResult(mapping, "invalid-source"));
+				result.providers.push(providerResult(mapping, "invalid-source", sourceCredential));
 				continue;
 			}
 
-			const existingCredential = piAuth[mapping.targetProvider];
+			const existingCredential = piAuth[resolvedTargetProvider];
 			if (sameCredential(existingCredential, nextCredential)) {
-				result.providers.push(providerResult(mapping, "already-imported"));
-				changedTargets.add(mapping.targetProvider);
+				result.providers.push(providerResult(mapping, "already-imported", sourceCredential));
+				changedTargets.add(resolvedTargetProvider);
 				continue;
 			}
 
 			if (existingCredential && !options.overwrite) {
-				result.providers.push(providerResult(mapping, "auth-exists-use-force"));
-				changedTargets.add(mapping.targetProvider);
+				result.providers.push(providerResult(mapping, "auth-exists-use-force", sourceCredential));
+				changedTargets.add(resolvedTargetProvider);
 				continue;
 			}
 
-			piAuth = { ...piAuth, [mapping.targetProvider]: nextCredential };
-			changedTargets.add(mapping.targetProvider);
-			result.providers.push(providerResult(mapping, "imported"));
+			piAuth = { ...piAuth, [resolvedTargetProvider]: nextCredential };
+			changedTargets.add(resolvedTargetProvider);
+			result.providers.push(providerResult(mapping, "imported", sourceCredential));
 		}
 
 		if (result.providers.some((provider) => provider.status === "imported")) {
@@ -206,3 +234,16 @@ export async function importOpencodeAccounts(options: OpencodeImportOptions = {}
 
 	return result;
 }
+
+function parseOpencodeAuthContent(content: string): OpencodeAuthData {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(content);
+	} catch {
+		throw new Error("OPENCODE_AUTH_CONTENT must contain a valid JSON object.");
+	}
+	if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+		throw new Error("OPENCODE_AUTH_CONTENT must contain a JSON object.");
+	}
+	return parsed as OpencodeAuthData;
+}

package/external/pi-tools-suite/src/opencode-import/index.ts

@@ -1,4 +1,4 @@
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 import { formatOpencodeImportResult, notificationLevel, parseOpencodeImportCommandArgs } from "./commands";
 import { importOpencodeAccounts } from "./importer";
 
@@ -8,10 +8,12 @@ export type { OpencodeImportOptions, OpencodeImportResult } from "./importer";
 
 export default function opencodeImport(pi: ExtensionAPI): void {
 	pi.registerCommand("opencode-import", {
-		description: "Import opencode auth.json credentials and Antigravity accounts into Pi/Pix auth.json",
-		handler: async (args: string, ctx: any) => {
+		description: "Import supported OpenCode credentials and Antigravity accounts into Pi/Pix auth.json",
+		handler: async (args: string, ctx: ExtensionCommandContext) => {
+			let wroteAuth = false;
 			try {
 				const result = await importOpencodeAccounts(parseOpencodeImportCommandArgs(args));
+				wroteAuth = result.wroteAuth;
 				const message = formatOpencodeImportResult(result);
 				if (ctx.ui?.notify) ctx.ui.notify(message, notificationLevel(result));
 				else console.log(message);
@@ -19,6 +21,15 @@ export default function opencodeImport(pi: ExtensionAPI): void {
 				const message = error instanceof Error ? error.message : String(error);
 				if (ctx.ui?.notify) ctx.ui.notify(message, "error");
 				else console.error(message);
+				return;
+			}
+
+			if (!wroteAuth) return;
+			try {
+				await ctx.reload();
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				console.error(`OpenCode credentials were imported, but resource reload failed: ${message}`);
 			}
 		},
 	});

package/external/pi-tools-suite/src/tool-descriptions.ts

@@ -221,10 +221,10 @@ export const TODO_TOOL_DESCRIPTION: ToolDescription = {
 		"Use `todo` for complex work with 3+ steps, explicit user task lists, or new non-trivial requirements. Skip single trivial tasks and purely conversational requests.",
 		"For multi-step implementation/debugging plans, include a final user-facing report todo in the initial plan with acceptance criteria for changed files/behavior, verification results, and remaining manual actions; close it immediately before the final response, never via compression.",
 		"When create or batch_create already sets the intended status, do not issue a redundant update with the same status; continue the work instead.",
-		"Resync before continuing when user/new findings change scope, requirements, safety, feasibility, approach, dependencies, or order; update tasks/blockers and defer obsolete work.",
+		"Resync before continuing when user/new findings change scope, requirements, safety, feasibility, approach, dependencies, or order. Before creating tasks, review pending/deferred todos; when work resumes, reactivate and reuse an equivalent deferred todo instead of duplicating it.",
 		"Update todos when starting, finishing, blocking, splitting, abandoning, or materially changing a step; before planned work mark exactly one in_progress with activeForm and complete it only after verification.",
 		"If partial, tests fail, or blocked, keep the task in_progress and add/update a blocker. Never use `clear`, `delete`, or batch deletion to hide unfinished/stale/forgotten todos; delete only on explicit request or creation mistake.",
-		"Before a final response after using todos, ensure each visible todo is completed, deferred, or intentionally still in_progress with explanation; do not leave a just-finished item in_progress.",
+		"Before a final response, list and reconcile all visible todos, including deferred ones: complete any whose outcome was achieved elsewhere, and leave deferred only genuinely unfinished or intentionally out of scope, mentioning each in the response. Do not finish with stale/duplicate deferred todos or a just-finished item in_progress.",
 		"Keep subjects short; use parentId/blockers for hierarchy/dependencies. For large explicit plans use batch_create/batch_update but keep exactly one visible in_progress unless asked otherwise; use batch_create replace:true only for superseding plans.",
 		"list hides tombstones unless includeDeleted:true; use status/blockedOnly only when needed; export/import for handoff, import replace:true only when explicitly overwriting; when all visible todos complete, state clears automatically.",
 		"Persistence: `/todos persist on|off|status` or `/todos-persist on|off|status`; on resume, ask in-scope ids and run `/todos scope <id...>` or `/todos-scope <id...>` so out-of-scope active tasks are deferred.",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-ui-extend",
-  "version": "0.1.74",
+  "version": "0.1.78",
   "description": "Pix: a workspace-first terminal UI for Pi with tabs, readable tool activity, voice input, and bundled agent tools.",
   "private": false,
   "repository": {

package/skills/context7/SKILL.md

@@ -9,6 +9,16 @@ This skill fetches current documentation and code examples for any programming l
 
 Context7 indexes documentation from official sources and provides version-specific, relevant excerpts — much more reliable than relying on potentially outdated training data.
 
+## Setup
+
+Create a Context7 API key in the Context7 dashboard and export it before using the skill:
+
+```bash
+export CONTEXT7_API_KEY="..."
+```
+
+The script does not contain a fallback key and exits before making a network request when the variable is missing. It also requires `curl` and `jq` on `PATH`.
+
 ## Two-step workflow
 
 ### Step 1: Resolve the library ID

package/skills/context7/scripts/context7.sh

@@ -10,11 +10,12 @@
 #   1. resolve — find the Context7 library ID for a package
 #   2. docs    — query documentation for a resolved library ID
 #
-# Requires CONTEXT7_API_KEY env var (falls back to hardcoded default).
+# Requires CONTEXT7_API_KEY env var.
 
 set -euo pipefail
 
-API_KEY="${CONTEXT7_API_KEY:-ctx7sk-d3b58838-f015-48a3-8059-93562f78837d}"
+: "${CONTEXT7_API_KEY:?Context7 requires CONTEXT7_API_KEY. Create a key at https://context7.com/dashboard and export it before using this skill.}"
+API_KEY="$CONTEXT7_API_KEY"
 BASE_URL="https://mcp.context7.com/mcp"
 
 call_mcp() {