@phi-code-admin/phi-code 0.84.1 → 0.85.0

package/dist/utils/version-check.d.ts

@@ -1,14 +1,14 @@
-export interface LatestPiRelease {
+export interface LatestRelease {
     version: string;
     packageName?: string;
 }
 export declare function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined;
 export declare function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean;
-export declare function getLatestPiRelease(currentVersion: string, options?: {
+export declare function getLatestRelease(currentVersion: string, options?: {
     timeoutMs?: number;
-}): Promise<LatestPiRelease | undefined>;
-export declare function getLatestPiVersion(currentVersion: string, options?: {
+}): Promise<LatestRelease | undefined>;
+export declare function getLatestVersion(currentVersion: string, options?: {
     timeoutMs?: number;
 }): Promise<string | undefined>;
-export declare function checkForNewPiVersion(currentVersion: string): Promise<string | undefined>;
+export declare function checkForNewVersion(currentVersion: string): Promise<string | undefined>;
 //# sourceMappingURL=version-check.d.ts.map

package/dist/utils/version-check.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,eAAe;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAsBD,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcpG;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAM/F;AAED,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC,CAmBtC;AAED,wBAAsB,kBAAkB,CACvC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE7B;AAED,wBAAsB,oBAAoB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU9F","sourcesContent":["import { getPiUserAgent } from \"./pi-user-agent.js\";\n\nconst LATEST_VERSION_URL = \"https://pi.dev/api/latest-version\";\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n}\n\ninterface ParsedVersion {\n\tmajor: number;\n\tminor: number;\n\tpatch: number;\n\tprerelease?: string;\n}\n\nfunction parsePackageVersion(version: string): ParsedVersion | undefined {\n\tconst match = version.trim().match(/^v?(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+.*)?$/);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tmajor: Number.parseInt(match[1], 10),\n\t\tminor: Number.parseInt(match[2], 10),\n\t\tpatch: Number.parseInt(match[3], 10),\n\t\tprerelease: match[4],\n\t};\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = parsePackageVersion(leftVersion);\n\tconst right = parsePackageVersion(rightVersion);\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\n\tif (left.major !== right.major) return left.major - right.major;\n\tif (left.minor !== right.minor) return left.minor - right.minor;\n\tif (left.patch !== right.patch) return left.patch - right.patch;\n\tif (left.prerelease === right.prerelease) return 0;\n\tif (!left.prerelease) return 1;\n\tif (!right.prerelease) return -1;\n\treturn left.prerelease.localeCompare(right.prerelease);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestPiRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(LATEST_VERSION_URL, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { packageName?: unknown; version?: unknown };\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName =\n\t\ttypeof data.packageName === \"string\" && data.packageName.trim() ? data.packageName.trim() : undefined;\n\treturn { version: data.version.trim(), packageName };\n}\n\nexport async function getLatestPiVersion(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestPiRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewPiVersion(currentVersion: string): Promise<string | undefined> {\n\ttry {\n\t\tconst latestVersion = await getLatestPiVersion(currentVersion);\n\t\tif (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {\n\t\t\treturn latestVersion;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}
+{"version":3,"file":"version-check.d.ts","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"AAUA,MAAM,WAAW,aAAa;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACrB;AAsBD,wBAAgB,sBAAsB,CAAC,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAcpG;AAED,wBAAgB,qBAAqB,CAAC,gBAAgB,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAM/F;AAED,wBAAsB,gBAAgB,CACrC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,aAAa,GAAG,SAAS,CAAC,CAkBpC;AAED,wBAAsB,gBAAgB,CACrC,cAAc,EAAE,MAAM,EACtB,OAAO,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GAClC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAE7B;AAED,wBAAsB,kBAAkB,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAU5F","sourcesContent":["import { PACKAGE_NAME } from \"../config.js\";\nimport { getPiUserAgent } from \"./pi-user-agent.js\";\n\n// Version checks query the npm registry for the published phi-code package.\n// (The inherited flow queried pi.dev, the upstream Pi endpoint, which reported\n// upstream Pi releases and made \"Update Available\" fire for versions of the\n// wrong product.)\nconst NPM_REGISTRY_URL = \"https://registry.npmjs.org\";\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n\nexport interface LatestRelease {\n\tversion: string;\n\tpackageName?: string;\n}\n\ninterface ParsedVersion {\n\tmajor: number;\n\tminor: number;\n\tpatch: number;\n\tprerelease?: string;\n}\n\nfunction parsePackageVersion(version: string): ParsedVersion | undefined {\n\tconst match = version.trim().match(/^v?(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+.*)?$/);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tmajor: Number.parseInt(match[1], 10),\n\t\tminor: Number.parseInt(match[2], 10),\n\t\tpatch: Number.parseInt(match[3], 10),\n\t\tprerelease: match[4],\n\t};\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = parsePackageVersion(leftVersion);\n\tconst right = parsePackageVersion(rightVersion);\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\n\tif (left.major !== right.major) return left.major - right.major;\n\tif (left.minor !== right.minor) return left.minor - right.minor;\n\tif (left.patch !== right.patch) return left.patch - right.patch;\n\tif (left.prerelease === right.prerelease) return 0;\n\tif (!left.prerelease) return 1;\n\tif (!right.prerelease) return -1;\n\treturn left.prerelease.localeCompare(right.prerelease);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(`${NPM_REGISTRY_URL}/${PACKAGE_NAME}/latest`, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { name?: unknown; version?: unknown };\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName = typeof data.name === \"string\" && data.name.trim() ? data.name.trim() : undefined;\n\treturn { version: data.version.trim(), packageName };\n}\n\nexport async function getLatestVersion(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewVersion(currentVersion: string): Promise<string | undefined> {\n\ttry {\n\t\tconst latestVersion = await getLatestVersion(currentVersion);\n\t\tif (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {\n\t\t\treturn latestVersion;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}

package/dist/utils/version-check.js

@@ -1,5 +1,10 @@
+import { PACKAGE_NAME } from "../config.js";
 import { getPiUserAgent } from "./pi-user-agent.js";
-const LATEST_VERSION_URL = "https://pi.dev/api/latest-version";
+// Version checks query the npm registry for the published phi-code package.
+// (The inherited flow queried pi.dev, the upstream Pi endpoint, which reported
+// upstream Pi releases and made "Update Available" fire for versions of the
+// wrong product.)
+const NPM_REGISTRY_URL = "https://registry.npmjs.org";
 const DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;
 function parsePackageVersion(version) {
     const match = version.trim().match(/^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+.*)?$/);
@@ -40,10 +45,10 @@ export function isNewerPackageVersion(candidateVersion, currentVersion) {
     }
     return candidateVersion.trim() !== currentVersion.trim();
 }
-export async function getLatestPiRelease(currentVersion, options = {}) {
+export async function getLatestRelease(currentVersion, options = {}) {
     if (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE)
         return undefined;
-    const response = await fetch(LATEST_VERSION_URL, {
+    const response = await fetch(`${NPM_REGISTRY_URL}/${PACKAGE_NAME}/latest`, {
         headers: {
             "User-Agent": getPiUserAgent(currentVersion),
             accept: "application/json",
@@ -56,15 +61,15 @@ export async function getLatestPiRelease(currentVersion, options = {}) {
     if (typeof data.version !== "string" || !data.version.trim()) {
         return undefined;
     }
-    const packageName = typeof data.packageName === "string" && data.packageName.trim() ? data.packageName.trim() : undefined;
+    const packageName = typeof data.name === "string" && data.name.trim() ? data.name.trim() : undefined;
     return { version: data.version.trim(), packageName };
 }
-export async function getLatestPiVersion(currentVersion, options = {}) {
-    return (await getLatestPiRelease(currentVersion, options))?.version;
+export async function getLatestVersion(currentVersion, options = {}) {
+    return (await getLatestRelease(currentVersion, options))?.version;
 }
-export async function checkForNewPiVersion(currentVersion) {
+export async function checkForNewVersion(currentVersion) {
     try {
-        const latestVersion = await getLatestPiVersion(currentVersion);
+        const latestVersion = await getLatestVersion(currentVersion);
         if (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {
             return latestVersion;
         }

package/dist/utils/version-check.js.map

@@ -1 +1 @@
-{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"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","sourcesContent":["import { getPiUserAgent } from \"./pi-user-agent.js\";\n\nconst LATEST_VERSION_URL = \"https://pi.dev/api/latest-version\";\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n\nexport interface LatestPiRelease {\n\tversion: string;\n\tpackageName?: string;\n}\n\ninterface ParsedVersion {\n\tmajor: number;\n\tminor: number;\n\tpatch: number;\n\tprerelease?: string;\n}\n\nfunction parsePackageVersion(version: string): ParsedVersion | undefined {\n\tconst match = version.trim().match(/^v?(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+.*)?$/);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tmajor: Number.parseInt(match[1], 10),\n\t\tminor: Number.parseInt(match[2], 10),\n\t\tpatch: Number.parseInt(match[3], 10),\n\t\tprerelease: match[4],\n\t};\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = parsePackageVersion(leftVersion);\n\tconst right = parsePackageVersion(rightVersion);\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\n\tif (left.major !== right.major) return left.major - right.major;\n\tif (left.minor !== right.minor) return left.minor - right.minor;\n\tif (left.patch !== right.patch) return left.patch - right.patch;\n\tif (left.prerelease === right.prerelease) return 0;\n\tif (!left.prerelease) return 1;\n\tif (!right.prerelease) return -1;\n\treturn left.prerelease.localeCompare(right.prerelease);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestPiRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestPiRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(LATEST_VERSION_URL, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { packageName?: unknown; version?: unknown };\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName =\n\t\ttypeof data.packageName === \"string\" && data.packageName.trim() ? data.packageName.trim() : undefined;\n\treturn { version: data.version.trim(), packageName };\n}\n\nexport async function getLatestPiVersion(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestPiRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewPiVersion(currentVersion: string): Promise<string | undefined> {\n\ttry {\n\t\tconst latestVersion = await getLatestPiVersion(currentVersion);\n\t\tif (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {\n\t\t\treturn latestVersion;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}
+{"version":3,"file":"version-check.js","sourceRoot":"","sources":["../../src/utils/version-check.ts"],"names":[],"mappings":"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","sourcesContent":["import { PACKAGE_NAME } from \"../config.js\";\nimport { getPiUserAgent } from \"./pi-user-agent.js\";\n\n// Version checks query the npm registry for the published phi-code package.\n// (The inherited flow queried pi.dev, the upstream Pi endpoint, which reported\n// upstream Pi releases and made \"Update Available\" fire for versions of the\n// wrong product.)\nconst NPM_REGISTRY_URL = \"https://registry.npmjs.org\";\nconst DEFAULT_VERSION_CHECK_TIMEOUT_MS = 10000;\n\nexport interface LatestRelease {\n\tversion: string;\n\tpackageName?: string;\n}\n\ninterface ParsedVersion {\n\tmajor: number;\n\tminor: number;\n\tpatch: number;\n\tprerelease?: string;\n}\n\nfunction parsePackageVersion(version: string): ParsedVersion | undefined {\n\tconst match = version.trim().match(/^v?(\\d+)\\.(\\d+)\\.(\\d+)(?:-([0-9A-Za-z.-]+))?(?:\\+.*)?$/);\n\tif (!match) {\n\t\treturn undefined;\n\t}\n\treturn {\n\t\tmajor: Number.parseInt(match[1], 10),\n\t\tminor: Number.parseInt(match[2], 10),\n\t\tpatch: Number.parseInt(match[3], 10),\n\t\tprerelease: match[4],\n\t};\n}\n\nexport function comparePackageVersions(leftVersion: string, rightVersion: string): number | undefined {\n\tconst left = parsePackageVersion(leftVersion);\n\tconst right = parsePackageVersion(rightVersion);\n\tif (!left || !right) {\n\t\treturn undefined;\n\t}\n\n\tif (left.major !== right.major) return left.major - right.major;\n\tif (left.minor !== right.minor) return left.minor - right.minor;\n\tif (left.patch !== right.patch) return left.patch - right.patch;\n\tif (left.prerelease === right.prerelease) return 0;\n\tif (!left.prerelease) return 1;\n\tif (!right.prerelease) return -1;\n\treturn left.prerelease.localeCompare(right.prerelease);\n}\n\nexport function isNewerPackageVersion(candidateVersion: string, currentVersion: string): boolean {\n\tconst comparison = comparePackageVersions(candidateVersion, currentVersion);\n\tif (comparison !== undefined) {\n\t\treturn comparison > 0;\n\t}\n\treturn candidateVersion.trim() !== currentVersion.trim();\n}\n\nexport async function getLatestRelease(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<LatestRelease | undefined> {\n\tif (process.env.PI_SKIP_VERSION_CHECK || process.env.PI_OFFLINE) return undefined;\n\n\tconst response = await fetch(`${NPM_REGISTRY_URL}/${PACKAGE_NAME}/latest`, {\n\t\theaders: {\n\t\t\t\"User-Agent\": getPiUserAgent(currentVersion),\n\t\t\taccept: \"application/json\",\n\t\t},\n\t\tsignal: AbortSignal.timeout(options.timeoutMs ?? DEFAULT_VERSION_CHECK_TIMEOUT_MS),\n\t});\n\tif (!response.ok) return undefined;\n\n\tconst data = (await response.json()) as { name?: unknown; version?: unknown };\n\tif (typeof data.version !== \"string\" || !data.version.trim()) {\n\t\treturn undefined;\n\t}\n\tconst packageName = typeof data.name === \"string\" && data.name.trim() ? data.name.trim() : undefined;\n\treturn { version: data.version.trim(), packageName };\n}\n\nexport async function getLatestVersion(\n\tcurrentVersion: string,\n\toptions: { timeoutMs?: number } = {},\n): Promise<string | undefined> {\n\treturn (await getLatestRelease(currentVersion, options))?.version;\n}\n\nexport async function checkForNewVersion(currentVersion: string): Promise<string | undefined> {\n\ttry {\n\t\tconst latestVersion = await getLatestVersion(currentVersion);\n\t\tif (latestVersion && isNewerPackageVersion(latestVersion, currentVersion)) {\n\t\t\treturn latestVersion;\n\t\t}\n\t\treturn undefined;\n\t} catch {\n\t\treturn undefined;\n\t}\n}\n"]}

package/docs/settings.md

@@ -50,9 +50,9 @@ Edit directly or use `/settings` for common options.
 
 ### Telemetry and update checks
 
-`enableInstallTelemetry` only controls the anonymous install/update ping to `https://pi.dev/api/report-install`. Opting out of telemetry does not disable update checks; Pi can still fetch `https://pi.dev/api/latest-version` to look for the latest version.
+phi-code sends no install/update telemetry (the inherited upstream ping to `pi.dev` was removed; `enableInstallTelemetry` is kept for settings compatibility but has no effect). The update check fetches `https://registry.npmjs.org/@phi-code-admin/phi-code/latest` to look for a newer phi-code release.
 
-Set `PI_SKIP_VERSION_CHECK=1` to disable the Pi version update check. Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks, package update checks, and install/update telemetry.
+Set `PI_SKIP_VERSION_CHECK=1` to disable the phi-code version update check. Use `--offline` or `PI_OFFLINE=1` to disable all startup network operations described here, including update checks and package update checks.
 
 ### Warnings
 

package/docs/usage.md

@@ -263,7 +263,7 @@ pi --tools read,grep,find,ls -p "Review the code"
 | `PI_CODING_AGENT_SESSION_DIR` | Override session storage directory; overridden by `--session-dir` |
 | `PI_PACKAGE_DIR` | Override package directory, useful for Nix/Guix store paths |
 | `PI_OFFLINE` | Disable startup network operations, including update checks, package update checks, and install/update telemetry |
-| `PI_SKIP_VERSION_CHECK` | Skip the Pi version update check at startup. This prevents the `pi.dev` latest-version request |
+| `PI_SKIP_VERSION_CHECK` | Skip the phi-code version update check at startup. This prevents the npm registry latest-version request |
 | `PI_TELEMETRY` | Override install/update telemetry: `1`/`true`/`yes` or `0`/`false`/`no`. This does not disable update checks |
 | `PI_CACHE_RETENTION` | Set to `long` for extended prompt cache where supported |
 | `VISUAL`, `EDITOR` | External editor for Ctrl+G |

package/examples/sdk/12-full-control.ts

@@ -26,7 +26,7 @@ if (process.env.MY_ANTHROPIC_KEY) {
 // Model registry with no custom models.json
 const modelRegistry = ModelRegistry.inMemory(authStorage);
 
-const model = getModel("anthropic", "claude-sonnet-4-20250514");
+const model = getModel("anthropic", "claude-sonnet-4-5");
 if (!model) throw new Error("Model not found");
 
 // In-memory settings with overrides

package/extensions/phi/mcp/index.ts

@@ -69,10 +69,9 @@ export default async function (pi: ExtensionAPI): Promise<void> {
     return;
   }
 
-  if (Object.keys(config.mcpServers).length === 0) {
-    // No servers configured — silently exit. Users can create mcp.json later.
-    return;
-  }
+  // Even with zero configured servers we proceed so the bundled `/mcp` command
+  // is always available (discoverability); it then guides the user to create an
+  // mcp.json. Servers are still only connected when one is actually configured.
 
   // ── 2. Initialize bridge components ──────────────────────────────────────
   // Auth callbacks — opens browser and notifies user when OAuth is needed
@@ -172,6 +171,13 @@ export default async function (pi: ExtensionAPI): Promise<void> {
           .filter(Boolean)
           .join("\n");
         ctx.ui.notify(detail, "info");
+      } else if (manager.getAllServers().length === 0) {
+        // No servers configured yet: guide the user instead of showing nothing.
+        ctx.ui.notify(
+          'No MCP servers configured. Create ~/.phi/agent/mcp.json (global) or .phi/mcp.json (project) with an "mcpServers" block, e.g.:\n' +
+            '{ "mcpServers": { "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."], "lifecycle": "eager" } } }',
+          "info",
+        );
       } else {
         // Summary view: all servers
         ctx.ui.notify(manager.getStatusSummary(), "info");

package/extensions/phi/models.ts

@@ -16,6 +16,7 @@
  */
 
 import { ApiKeyStore, type ConfigWatcher, type ExtensionAPI, getApiKeyStore, getConfigWatcher } from "phi-code";
+import { getModels } from "phi-code-ai";
 import {
 	buildOpenCodeGoAnthropicProviderConfig,
 	buildOpenCodeGoProviderConfig,
@@ -25,7 +26,9 @@ import { formatWindow, inferContextWindow, parseContextWindow } from "./provider
 import { fetchLiveModels, peekCache, resetLiveModelsCache, toPersistedModel } from "./providers/live-models.js";
 
 const PROVIDER_DISPLAY: Record<string, string> = {
+	opencode: "OpenCode Zen",
 	"opencode-go": "OpenCode Go",
+	"opencode-go-anthropic": "OpenCode Go (Anthropic-compat)",
 	"alibaba-codingplan": "Alibaba Coding Plan (OpenAI-compat)",
 	"alibaba-codingplan-anthropic": "Alibaba Coding Plan (Anthropic-compat)",
 	openai: "OpenAI",
@@ -37,10 +40,62 @@ const PROVIDER_DISPLAY: Record<string, string> = {
 	"lm-studio": "LM Studio (local)",
 };
 
+/**
+ * Providers the live-models dispatcher can actually re-fetch (see
+ * live-models.ts dispatchFetch + refreshOpenCodeGo). Used to extend the
+ * startup/manual refresh to providers that are authenticated via auth.json or
+ * env vars but have no models.json entry yet — without it, a user who set a
+ * key with /auth (and never ran /setup) would never see new upstream models.
+ */
+const REFRESHABLE_PROVIDERS: ReadonlySet<string> = new Set([
+	"opencode",
+	"opencode-go",
+	"opencode-go-anthropic",
+	"alibaba-codingplan",
+	"alibaba-codingplan-anthropic",
+	"openai",
+	"anthropic",
+	"google",
+	"openrouter",
+	"groq",
+	"ollama",
+	"lm-studio",
+]);
+
 function displayName(id: string): string {
 	return PROVIDER_DISPLAY[id] ?? id;
 }
 
+/** Default discovery base URLs for providers whose models.json entry is created by a refresh. */
+const DEFAULT_BASE_URLS: Record<string, string> = {
+	opencode: "https://opencode.ai/zen/v1",
+	"opencode-go": "https://opencode.ai/zen/go/v1",
+	"alibaba-codingplan": "https://coding-intl.dashscope.aliyuncs.com/v1",
+	"alibaba-codingplan-anthropic": "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic",
+	openai: "https://api.openai.com/v1",
+	anthropic: "https://api.anthropic.com/v1",
+	google: "https://generativelanguage.googleapis.com/v1beta",
+	openrouter: "https://openrouter.ai/api/v1",
+	groq: "https://api.groq.com/openai/v1",
+	ollama: "http://localhost:11434/v1",
+	"lm-studio": "http://localhost:1234/v1",
+};
+
+/**
+ * Built-in (models.generated.ts) model ids for a provider. Persisting only the
+ * models NOT in this set keeps the rich built-in definitions (costs, image
+ * input, thinking-level maps) authoritative — models.json carries just the
+ * delta the static catalog does not know about yet.
+ */
+function builtinModelIds(providerId: string): Set<string> {
+	try {
+		const models = getModels(providerId as Parameters<typeof getModels>[0]) as Array<{ id: string }>;
+		return new Set(models.map((m) => m.id));
+	} catch {
+		return new Set();
+	}
+}
+
 interface RefreshOutcome {
 	provider: string;
 	source: "live" | "cache" | "fallback" | "unsupported" | "skipped";
@@ -68,7 +123,21 @@ async function refreshOpenCodeGo(
 			? buildOpenCodeGoAnthropicProviderConfig(keyForBuild, models)
 			: buildOpenCodeGoProviderConfig(keyForBuild, models);
 
-	if (config.models.length === 0) {
+	// Persist only models the built-in catalog does not know yet; built-ins stay
+	// authoritative (costs, image input) and models.json carries the delta.
+	const builtin = builtinModelIds(providerId);
+	const newModels = config.models.filter((m) => !builtin.has(m.id));
+
+	if (newModels.length === 0) {
+		if (stored && Array.isArray(stored.models) && stored.models.length > 0) {
+			// Clean up previously persisted models that have since become built-in.
+			watcher.muteForWrite("models_json_changed");
+			store.setKey(providerId, stored.apiKey ?? apiKey ?? "local", {
+				baseUrl: stored.baseUrl ?? config.baseUrl,
+				api: stored.api ?? config.api,
+				models: [],
+			});
+		}
 		return { provider: providerId, source: source === "fallback" ? "fallback" : "skipped", count: 0 };
 	}
 
@@ -76,22 +145,26 @@ async function refreshOpenCodeGo(
 	store.setKey(providerId, stored?.apiKey ?? apiKey ?? "local", {
 		baseUrl: stored?.baseUrl ?? config.baseUrl,
 		api: stored?.api ?? config.api,
-		models: config.models,
+		models: newModels,
 	});
 
 	const outcomeSource = source === "live" ? "live" : source === "cache" ? "cache" : "fallback";
-	return { provider: providerId, source: outcomeSource, count: config.models.length };
+	return { provider: providerId, source: outcomeSource, count: newModels.length };
 }
 
 async function refreshOne(
 	store: ApiKeyStore,
 	watcher: ConfigWatcher,
 	providerId: string,
+	resolvedApiKey?: string,
 ): Promise<RefreshOutcome> {
 	const stored = store.getProvider(providerId);
-	const apiKey = stored?.apiKey && !stored.apiKey.startsWith("$") && stored.apiKey !== "local"
+	const storedKey = stored?.apiKey && !stored.apiKey.startsWith("$") && stored.apiKey !== "local"
 		? stored.apiKey
 		: undefined;
+	// Prefer the key stored in models.json, else the one resolved from
+	// auth.json/env by the model registry (providers set up via /auth only).
+	const apiKey = storedKey ?? resolvedApiKey;
 
 	// OpenCode Go is a provider pair the generic fetchLiveModels path can't express
 	// (and never handled the Anthropic side), so refresh it from the shared catalog.
@@ -110,40 +183,30 @@ async function refreshOne(
 		return { provider: providerId, source: "skipped", count: 0, error: result.error };
 	}
 
-	const persisted = result.models.map(toPersistedModel);
-	if (persisted.length === 0) {
-		return { provider: providerId, source: result.source, count: 0, error: result.error };
-	}
+	// Persist only the delta the built-in catalog does not know yet (see
+	// builtinModelIds). Built-in definitions keep their costs/capabilities.
+	const builtin = builtinModelIds(providerId);
+	const persisted = result.models.map(toPersistedModel).filter((m) => !builtin.has(m.id));
 
 	// Preserve baseUrl/api/apiKey/headers from existing config; only models change.
-	const baseUrl =
-		stored?.baseUrl ??
-		(providerId === "opencode-go"
-			? "https://opencode.ai/zen/go/v1"
-			: providerId === "alibaba-codingplan"
-				? "https://coding-intl.dashscope.aliyuncs.com/v1"
-				: providerId === "alibaba-codingplan-anthropic"
-					? "https://coding-intl.dashscope.aliyuncs.com/apps/anthropic"
-					: providerId === "openai"
-						? "https://api.openai.com/v1"
-						: providerId === "anthropic"
-							? "https://api.anthropic.com/v1"
-							: providerId === "google"
-								? "https://generativelanguage.googleapis.com/v1beta"
-								: providerId === "openrouter"
-									? "https://openrouter.ai/api/v1"
-									: providerId === "groq"
-										? "https://api.groq.com/openai/v1"
-										: providerId === "ollama"
-											? "http://localhost:11434/v1"
-											: providerId === "lm-studio"
-												? "http://localhost:1234/v1"
-												: undefined);
-
+	const baseUrl = stored?.baseUrl ?? DEFAULT_BASE_URLS[providerId];
 	if (!baseUrl) {
 		return { provider: providerId, source: "skipped", count: 0, error: "unknown baseUrl" };
 	}
 
+	if (persisted.length === 0) {
+		if (stored && Array.isArray(stored.models) && stored.models.length > 0) {
+			// Clean up previously persisted models that have since become built-in.
+			watcher.muteForWrite("models_json_changed");
+			store.setKey(providerId, stored.apiKey ?? "local", {
+				baseUrl,
+				api: stored.api,
+				models: [],
+			});
+		}
+		return { provider: providerId, source: result.source, count: 0, error: result.error };
+	}
+
 	// Mute the config watcher so it does not echo this programmatic write back
 	// as a models_json_changed event (which would trigger a spurious reload +
 	// "Keys reloaded" notification). Mute per-write because refresh loops can
@@ -311,29 +374,73 @@ export default function modelsExtension(pi: ExtensionAPI) {
 		ctx.ui.notify(out, "info");
 	}
 
+	interface RefreshTarget {
+		id: string;
+		resolvedApiKey?: string;
+	}
+
+	/**
+	 * Providers to refresh: every provider persisted in models.json, plus every
+	 * refreshable provider that is authenticated (auth.json / env vars) but has
+	 * no models.json entry yet. API keys are resolved through the registry so
+	 * providers configured via /auth alone still get authenticated listings.
+	 */
+	async function resolveRefreshTargets(registry: {
+		getAvailable(): Array<{ provider: string }>;
+		getApiKeyForProvider(provider: string): Promise<string | undefined>;
+	}): Promise<RefreshTarget[]> {
+		const targets = new Map<string, RefreshTarget>();
+		for (const id of store.listProviders()) {
+			targets.set(id, { id });
+		}
+		try {
+			for (const model of registry.getAvailable()) {
+				const id = model.provider;
+				if (!targets.has(id) && REFRESHABLE_PROVIDERS.has(id)) {
+					targets.set(id, { id });
+				}
+			}
+		} catch {
+			// registry unavailable — fall back to models.json providers only
+		}
+		for (const target of targets.values()) {
+			try {
+				target.resolvedApiKey = await registry.getApiKeyForProvider(target.id);
+			} catch {
+				// no resolvable key — refreshOne will try the stored/keyless path
+			}
+		}
+		return [...targets.values()];
+	}
+
 	// Background refresh on session_start so every new Phi Code session reflects
 	// the latest provider catalogs without the user typing `/models refresh`.
 	// Failures are silent — startup must never be blocked by upstream API hiccups.
 	pi.on("session_start", async (_event, ctx) => {
+		if (process.env.PI_OFFLINE) return;
 		try {
 			store.load();
 		} catch {
 			// no models.json yet
 		}
-		const providers = store.listProviders();
-		if (providers.length === 0) return;
+		const targets = await resolveRefreshTargets(ctx.modelRegistry);
+		if (targets.length === 0) return;
 
 		// Fire-and-forget. Hot-reload via models_json_changed event surfaces results.
 		void (async () => {
-			let changed = 0;
-			for (const id of providers) {
-				const outcome = await refreshOne(store, watcher, id).catch(() => undefined);
-				if (outcome && outcome.source === "live" && outcome.count > 0) changed++;
+			let discovered = 0;
+			let changedProviders = 0;
+			for (const target of targets) {
+				const outcome = await refreshOne(store, watcher, target.id, target.resolvedApiKey).catch(() => undefined);
+				if (outcome && outcome.source === "live" && outcome.count > 0) {
+					changedProviders++;
+					discovered += outcome.count;
+				}
 			}
-			if (changed > 0) {
+			if (changedProviders > 0) {
 				try {
 					ctx.ui.notify(
-						`Refreshed ${changed}/${providers.length} provider catalog(s) in the background.`,
+						`Discovered ${discovered} new model(s) across ${changedProviders} provider(s). See /model.`,
 						"info",
 					);
 				} catch {
@@ -346,20 +453,33 @@ export default function modelsExtension(pi: ExtensionAPI) {
 
 	async function refreshCommand(
 		target: string | undefined,
-		ctx: { ui: { notify: (m: string, t?: "info" | "warning" | "error") => void; setStatus?: (k: string, v?: string) => void } },
+		ctx: {
+			ui: { notify: (m: string, t?: "info" | "warning" | "error") => void; setStatus?: (k: string, v?: string) => void };
+			modelRegistry: {
+				getAvailable(): Array<{ provider: string }>;
+				getApiKeyForProvider(provider: string): Promise<string | undefined>;
+			};
+		},
 	): Promise<void> {
-		const providers = target ? [target] : store.listProviders();
-		if (providers.length === 0) {
+		const targets = target ? [{ id: target } as RefreshTarget] : await resolveRefreshTargets(ctx.modelRegistry);
+		if (target) {
+			try {
+				targets[0].resolvedApiKey = await ctx.modelRegistry.getApiKeyForProvider(target);
+			} catch {
+				// keep undefined
+			}
+		}
+		if (targets.length === 0) {
 			ctx.ui.notify("No providers configured.", "warning");
 			return;
 		}
-		ctx.ui.notify(`Refreshing ${providers.length} provider(s)...`, "info");
+		ctx.ui.notify(`Refreshing ${targets.length} provider(s)...`, "info");
 		ctx.ui.setStatus?.("models-refresh", "Fetching live model catalogs...");
 
 		const outcomes: RefreshOutcome[] = [];
-		for (const id of providers) {
-			const outcome = await refreshOne(store, watcher, id).catch((err) => ({
-				provider: id,
+		for (const t of targets) {
+			const outcome = await refreshOne(store, watcher, t.id, t.resolvedApiKey).catch((err) => ({
+				provider: t.id,
 				source: "skipped" as const,
 				count: 0,
 				error: err instanceof Error ? err.message : String(err),
@@ -371,9 +491,10 @@ export default function modelsExtension(pi: ExtensionAPI) {
 		let out = "**Refresh report:**\n";
 		for (const o of outcomes) {
 			const icon = o.source === "live" ? "[ok]" : o.source === "fallback" ? "[fb]" : o.source === "cache" ? "[c]" : "[--]";
-			out += `  ${icon} ${displayName(o.provider)} \`${o.provider}\` — ${o.count} model(s) (${o.source}${o.error ? `, ${o.error}` : ""})\n`;
+			out += `  ${icon} ${displayName(o.provider)} \`${o.provider}\` — ${o.count} new model(s) (${o.source}${o.error ? `, ${o.error}` : ""})\n`;
 		}
-		out += `\nModels persisted to \`${store.configPath}\`. \`/model\` picker now reflects this catalog.`;
+		out += `\nOnly models missing from the built-in catalog are persisted to \`${store.configPath}\`;\n`;
+		out += `built-in models stay available either way. \`/model\` picker reflects the merged catalog.`;
 		ctx.ui.notify(out, "info");
 		pi.events.emit("models_json_changed", { source: "models-refresh" });
 	}

package/extensions/phi/orchestrator.ts

@@ -359,6 +359,28 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 		return null;
 	}
 
+	/**
+	 * Load a skill body (SKILL.md) so a phase instruction can embed it verbatim.
+	 * Search order mirrors loadAgentDef: project .phi/skills first, then the
+	 * global ~/.phi/agent/skills (where postinstall copies the bundled skills).
+	 * YAML frontmatter is stripped. Returns null when the skill is not installed.
+	 */
+	function loadSkillContent(name: string): string | null {
+		const dirs = [
+			join(process.cwd(), ".phi", "skills"),
+			join(homedir(), ".phi", "agent", "skills"),
+		];
+		for (const dir of dirs) {
+			try {
+				const content = readFileSync(join(dir, name, "SKILL.md"), "utf-8");
+				const fmMatch = content.match(/^---\s*\n[\s\S]*?\n---\s*\n([\s\S]*)$/);
+				const body = (fmMatch ? fmMatch[1] : content).trim();
+				if (body) return body;
+			} catch { /* try next dir */ }
+		}
+		return null;
+	}
+
 	/**
 	 * Load routing config and build phase queue with model assignments + agent definitions.
 	 * Each phase now reads outputs from previous phases and writes structured outputs.
@@ -392,6 +414,15 @@ export default function orchestratorExtension(pi: ExtensionAPI) {
 			: '';
 		const runtimeInfo = `\n\nRuntime: ${process.platform} (${process.arch})${shellNote}`;
 
+		// Embed the prompt-architect skill so the PLAN phase applies it to every
+		// task it writes. The skill ships bundled and is copied to
+		// ~/.phi/agent/skills by postinstall; when missing, the inline task format
+		// still enforces the [CONTEXT]/[TASK]/[FORMAT]/[CONSTRAINTS] structure.
+		const promptArchitectSkill = loadSkillContent("prompt-architect");
+		const promptArchitectSection = promptArchitectSkill
+			? `\n**Prompt-architect skill (apply it to every task you write):**\n\n${promptArchitectSkill}\n`
+			: "";
+
 		const phases: OrchestratorPhase[] = [
 			{
 				key: "explore", label: "🔍 Phase 1 — EXPLORE", model: explore.preferred, fallback: explore.fallback,
@@ -466,29 +497,37 @@ After your analysis, use \`ontology_add\` to save key project entities AND their
 **Step 1:** Read \`.phi/plans/brief-*.md\` (created by the explore phase)
 **Step 2:** Read \`.phi/plans/explore-*.md\` to understand the codebase analysis
 **Step 3:** Design the architecture based on findings
-**Step 4:** Create a DETAILED TODO LIST in \`.phi/plans/todo-${ts}.md\`:
-   For each task:
-   - Task number and title
-   - Agent assignment (code/test)
-   - Files to create/modify
-   - Specific implementation details
-   - Dependencies on other tasks
+**Step 4:** Create a DETAILED TODO LIST in \`.phi/plans/todo-${ts}.md\`.
+   Every task is a PROMPT for the CODE agent, which starts with ZERO memory of
+   this conversation. Write each task with the prompt-architect structure:
+   - **[CONTEXT]** what exists and why this task (real paths from the explore phase)
+   - **[TASK]** exactly what to do — files to create/modify with full paths
+   - **[FORMAT]** expected deliverable — exports, signatures, style, tests
+   - **[CONSTRAINTS]** what NOT to break, patterns to respect
+   Plus: task number + title, agent assignment (code/test), dependencies.
 
 **Format for the todo list:**
 \`\`\`markdown
 # TODO: Project Tasks
 
 ## Task 1: [Task Title] [agent-type]
-- [ ] Specific implementation details
-- [ ] Files to create: path/to/file.ext
-- [ ] Expected behavior
+**[CONTEXT]** [What exists now, why this task, real paths (src/x.ts:42)]
+**[TASK]**
+- [ ] Create path/to/file.ext with [specific behavior]
+- [ ] Modify path/to/other.ext: [exact change]
+**[FORMAT]** [Expected exports/signatures/tests]
+**[CONSTRAINTS]** [What not to break, patterns to follow]
 - Dependencies: None
 
 ## Task 2: [Task Title] [agent-type]
-- [ ] Implementation details
+**[CONTEXT]** ...
+**[TASK]**
+- [ ] ...
+**[FORMAT]** ...
+**[CONSTRAINTS]** ...
 - Dependencies: Task 1
 \`\`\`
-
+${promptArchitectSection}
 Before finishing, use \`memory_write\` to save your plan summary with relevant tags for future reference.` + runtimeInfo + COMMON_PHASE_RULES,
 			},
 			{