@piagent/platform 1.1.9 → 1.2.0

package/packages/piagent-core/mcp/mcp-server-catalog.js

@@ -0,0 +1,150 @@
+// The servers this platform ships a pinned definition for, and the presets that
+// group them. Pinned by version or digest because an MCP server is code that runs
+// on the operator's machine with the operator's credentials; a floating tag would
+// make every session a fresh supply-chain decision nobody is present to make.
+//
+// Nothing here is a secret. Every credential is referenced as an environment
+// variable, so the config can be read, diffed and committed without leaking one.
+
+/** @typedef {{description: string, config: Record<string, unknown>}} CatalogServer */
+
+/** @type {Record<string, CatalogServer>} */
+export const CATALOG_SERVERS = {
+  context7: {
+    description: "Official Context7 MCP server for up-to-date library/framework docs.",
+    config: {
+      command: "npx",
+      args: ["-y", "@upstash/context7-mcp@3.2.4"],
+      env: {
+        CONTEXT7_API_KEY: "${CONTEXT7_API_KEY}"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "chrome-devtools": {
+    description: "Chrome DevTools MCP for runtime browser inspection, console logs, screenshots, and performance checks.",
+    config: {
+      command: "npx",
+      args: ["-y", "chrome-devtools-mcp@1.6.0", "--no-performance-crux"],
+      env: {
+        CHROME_DEVTOOLS_MCP_NO_USAGE_STATISTICS: "1",
+        CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS: "1"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  playwright: {
+    description: "Playwright MCP for browser automation and UI verification workflows.",
+    config: {
+      command: "npx",
+      args: ["-y", "@playwright/mcp@0.0.78"],
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  github: {
+    description: "Official GitHub MCP server via Docker. Requires Docker and GITHUB_PERSONAL_ACCESS_TOKEN when used.",
+    config: {
+      command: "docker",
+      args: [
+        "run",
+        "-i",
+        "--rm",
+        "-e",
+        "GITHUB_PERSONAL_ACCESS_TOKEN",
+        "-e",
+        "GITHUB_READ_ONLY=1",
+        "-e",
+        "GITHUB_LOCKDOWN_MODE=1",
+        "ghcr.io/github/github-mcp-server@sha256:2b0c48b070f61e9d3969269ead600f62d00fb237b60ac849ef3d166ee7de9ad3"
+      ],
+      env: {
+        GITHUB_PERSONAL_ACCESS_TOKEN: "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      },
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  figma: {
+    description: "Figma remote MCP server. Requires Figma OAuth from the MCP panel when first used.",
+    config: {
+      url: "https://mcp.figma.com/mcp",
+      auth: "oauth",
+      lifecycle: "lazy",
+      directTools: false
+    }
+  },
+  "figma-desktop": {
+    description: "Figma desktop/local MCP server. Requires Figma desktop Dev Mode MCP enabled.",
+    config: {
+      url: "http://127.0.0.1:3845/mcp",
+      lifecycle: "lazy",
+      directTools: false
+    }
+  }
+};
+
+// Writing a server definition does not make it usable. What each one still needs
+// from the operator is stated here so it can be printed at the moment the
+// definition is written, rather than living only in a description string that
+// shows up under --list.
+/** @type {Record<string, string[]>} */
+export const CATALOG_PREREQUISITES = {
+  context7: ["optional: export CONTEXT7_API_KEY for a higher documentation quota"],
+  "chrome-devtools": ["a local Chrome installation"],
+  github: [
+    "Docker running",
+    "export GITHUB_PERSONAL_ACCESS_TOKEN with the scopes you intend to use"
+  ],
+  playwright: ["browsers installed on first use (npx playwright install)"],
+  figma: ["Figma OAuth, completed from the Pi MCP panel on first use"],
+  "figma-desktop": ["Figma desktop running with Dev Mode MCP enabled"]
+};
+
+// Variables a pinned server references but works without. Context7 answers
+// without a key and the key only raises the quota, so reporting it as missing
+// would put a line in front of the operator every session about something that
+// is not wrong. A server somebody adds by hand has no entry here: they typed the
+// reference, so it is treated as one they meant.
+/** @type {Record<string, string[]>} */
+export const CATALOG_OPTIONAL_ENV = {
+  context7: ["CONTEXT7_API_KEY"]
+};
+
+/** @type {Record<string, string[]>} */
+export const CATALOG_PRESETS = {
+  minimal: [],
+  docs: ["context7"],
+  browser: ["chrome-devtools", "playwright"],
+  github: ["github"],
+  design: ["figma"],
+  "design-local": ["figma-desktop"],
+  web: ["context7", "chrome-devtools", "playwright"],
+  core: ["context7", "chrome-devtools", "github"],
+  popular: ["context7", "chrome-devtools", "playwright", "github", "figma"],
+  all: ["context7", "chrome-devtools", "playwright", "github", "figma", "figma-desktop"]
+};
+
+/** @param {string} name @returns {boolean} */
+export function isCatalogPreset(name) {
+  return Object.hasOwn(CATALOG_PRESETS, name);
+}
+
+/**
+ * The servers a preset installs, with their definitions resolved. Throws on an
+ * unknown preset so a typo is refused before anything is written.
+ * @param {string} name
+ * @returns {{name: string, config: Record<string, unknown>, requires: string[]}[]}
+ */
+export function resolvePreset(name) {
+  if (!isCatalogPreset(name)) {
+    throw new Error(`unknown preset: ${name}. Available presets: ${Object.keys(CATALOG_PRESETS).join(", ")}`);
+  }
+  return CATALOG_PRESETS[name].map((serverName) => {
+    const server = CATALOG_SERVERS[serverName];
+    if (!server) throw new Error(`preset ${name} references missing server ${serverName}`);
+    return { name: serverName, config: server.config, requires: CATALOG_PREREQUISITES[serverName] ?? [] };
+  });
+}

package/packages/piagent-core/mcp/mcp-server-entry.js

@@ -0,0 +1,242 @@
+import { containsSensitiveText } from "../security/sensitive-data.js";
+
+// Building a server definition from what someone typed. The rule this file
+// exists to hold: a credential never reaches the config file.
+//
+// MCP config is read by several clients, lives in the operator's home or in a
+// repository, and in the `project` scope is meant to be committed. A token typed
+// into `--env` would land in all of those. So a value whose name says credential
+// has to be an environment reference, and the error says which form to use rather
+// than only that the input was refused.
+
+const SERVER_NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+// A whole-value reference, `${VAR}`. A value that merely contains one — say
+// `Bearer ${TOKEN}` — is handled separately, because a header legitimately needs
+// the scheme in front of the reference.
+const ENV_REFERENCE = /^\$\{[A-Za-z_][A-Za-z0-9_]*\}$/;
+const CONTAINS_ENV_REFERENCE = /\$\{[A-Za-z_][A-Za-z0-9_]*\}/;
+
+const CREDENTIAL_NAME_TERMS = [
+  "token", "secret", "password", "passwd", "passphrase", "credential",
+  "apikey", "api_key", "accesskey", "access_key", "privatekey", "private_key",
+  "authorization", "auth", "session", "cookie", "signature", "pat"
+];
+
+export class McpEntryError extends Error {}
+
+/**
+ * Whether a name says the value beside it is a credential. Deliberately broad:
+ * a false positive costs one `${VAR}` indirection, a false negative writes a
+ * live token into a file somebody commits.
+ * @param {string} name
+ * @returns {boolean}
+ */
+export function credentialLikeName(name) {
+  const normalized = String(name).toLowerCase().replace(/[^a-z0-9]+/g, "_");
+  return CREDENTIAL_NAME_TERMS.some((term) => {
+    const bare = term.replace(/[^a-z0-9]+/g, "_");
+    return normalized === bare || normalized.startsWith(`${bare}_`) || normalized.endsWith(`_${bare}`) || normalized.includes(`_${bare}_`);
+  });
+}
+
+/**
+ * @param {string} raw `KEY=VALUE`
+ * @param {"env"|"header"} kind
+ * @returns {[string, string]}
+ */
+export function parseAssignment(raw, kind) {
+  const separator = kind === "header" ? ":" : "=";
+  const index = String(raw).indexOf(separator);
+  if (index <= 0) {
+    throw new McpEntryError(
+      kind === "header"
+        ? `--header expects "Name: value", received: ${raw}`
+        : `--env expects KEY=value, received: ${raw}`
+    );
+  }
+  const name = raw.slice(0, index).trim();
+  const value = raw.slice(index + 1).trim();
+  if (!name) throw new McpEntryError(`${kind} name cannot be empty`);
+  return [name, value];
+}
+
+/**
+ * Refuse a literal credential, and say what to type instead. `kind` only shapes
+ * the message; both channels are held to the same rule.
+ * @param {string} name
+ * @param {string} value
+ * @param {"env"|"header"} kind
+ * @returns {void}
+ */
+export function assertNoLiteralSecret(name, value, kind) {
+  const referenced = kind === "header" ? CONTAINS_ENV_REFERENCE.test(value) : ENV_REFERENCE.test(value);
+  if (referenced) return;
+
+  const suggestion = kind === "header"
+    ? `--header '${name}: Bearer \${${suggestedVariable(name)}}'`
+    : `--env '${name}=\${${suggestedVariable(name)}}'`;
+
+  if (credentialLikeName(name)) {
+    throw new McpEntryError(
+      `${name} names a credential, so its value cannot be written into MCP config. ` +
+      `Export it in your shell and reference it instead: ${suggestion}`
+    );
+  }
+  // The name gave nothing away, so the value is read on its own. This catches a
+  // token pasted under a neutral name such as `--env CONFIG=ghp_...`.
+  if (containsSensitiveText(`${name}=${value}`)) {
+    throw new McpEntryError(
+      `the value given for ${name} looks like a credential, so it cannot be written into MCP config. ` +
+      `Export it in your shell and reference it instead: ${suggestion}`
+    );
+  }
+}
+
+/** @param {string} name @returns {string} */
+function suggestedVariable(name) {
+  const upper = String(name).toUpperCase().replace(/[^A-Z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+  return upper || "TOKEN";
+}
+
+/** @param {string} name @returns {string} */
+export function assertServerName(name) {
+  if (!SERVER_NAME.test(String(name ?? ""))) {
+    throw new McpEntryError(
+      `invalid server name: ${name}. Use letters, digits, dot, dash or underscore, up to 64 characters.`
+    );
+  }
+  return name;
+}
+
+/**
+ * @typedef {object} BuildEntryInput
+ * @property {string} name
+ * @property {string} [url]
+ * @property {string[]} [command] argv, first element is the executable
+ * @property {string[]} [env] raw `KEY=value`
+ * @property {string[]} [header] raw `Name: value`
+ * @property {string} [bearerTokenEnvVar]
+ * @property {string} [oauthClientId]
+ * @property {string} [oauthScopes]
+ * @property {boolean} [directTools]
+ */
+
+/**
+ * @param {BuildEntryInput} input
+ * @returns {Record<string, unknown>}
+ */
+export function buildServerEntry(input) {
+  assertServerName(input.name);
+  const hasUrl = typeof input.url === "string" && input.url.length > 0;
+  const hasCommand = Array.isArray(input.command) && input.command.length > 0;
+  if (hasUrl === hasCommand) {
+    throw new McpEntryError("give either --url for a remote server or -- <command> for a local one, not both and not neither");
+  }
+
+  /** @type {Record<string, unknown>} */
+  const entry = { lifecycle: "lazy", directTools: input.directTools === true };
+
+  if (hasUrl) {
+    const url = parseRemoteUrl(input.url ?? "");
+    entry.url = url.href;
+    if (input.oauthClientId || input.oauthScopes) {
+      /** @type {Record<string, unknown>} */
+      const oauth = {};
+      if (input.oauthClientId) oauth.clientId = input.oauthClientId;
+      if (input.oauthScopes) oauth.scopes = input.oauthScopes;
+      entry.auth = "oauth";
+      entry.oauth = oauth;
+    }
+    if (input.bearerTokenEnvVar) {
+      // The variable name, never the token. Whoever reads the config learns which
+      // variable to export and nothing else.
+      entry.bearerTokenEnvVar = assertEnvVarName(input.bearerTokenEnvVar);
+    }
+    const headers = collectAssignments(input.header ?? [], "header");
+    if (Object.keys(headers).length > 0) entry.headers = headers;
+  } else {
+    const argv = input.command ?? [];
+    entry.command = argv[0];
+    if (argv.length > 1) entry.args = argv.slice(1);
+    const env = collectAssignments(input.env ?? [], "env");
+    if (Object.keys(env).length > 0) entry.env = env;
+    if (input.header?.length) throw new McpEntryError("--header applies to remote servers; a local server takes --env");
+    if (input.bearerTokenEnvVar) throw new McpEntryError("--bearer-token-env-var applies to remote servers only");
+  }
+
+  return entry;
+}
+
+/** @param {string[]} raw @param {"env"|"header"} kind @returns {Record<string, string>} */
+function collectAssignments(raw, kind) {
+  /** @type {Record<string, string>} */
+  const out = {};
+  for (const item of raw) {
+    const [name, value] = parseAssignment(item, kind);
+    assertNoLiteralSecret(name, value, kind);
+    out[name] = value;
+  }
+  return out;
+}
+
+/** @param {string} value @returns {string} */
+function assertEnvVarName(value) {
+  if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+    throw new McpEntryError(`--bearer-token-env-var expects a variable name, received: ${value}`);
+  }
+  return value;
+}
+
+/**
+ * A remote server has to be reachable over a transport this platform is willing
+ * to describe as one. `http://` is allowed only on the loopback address, where
+ * there is no network to intercept — Figma's desktop server is exactly that case.
+ * @param {string} value
+ * @returns {URL}
+ */
+export function parseRemoteUrl(value) {
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    throw new McpEntryError(`--url is not a valid URL: ${value}`);
+  }
+  if (url.protocol === "https:") return url;
+  if (url.protocol === "http:" && isLoopbackHost(url.hostname)) return url;
+  throw new McpEntryError(
+    `--url must be https, or http on localhost. Received: ${url.protocol}//${url.hostname}`
+  );
+}
+
+/** @param {string} hostname @returns {boolean} */
+function isLoopbackHost(hostname) {
+  const host = hostname.replace(/^\[|\]$/g, "").toLowerCase();
+  return host === "localhost" || host === "127.0.0.1" || host === "::1";
+}
+
+/**
+ * A server entry with every value that could be a credential replaced. Used for
+ * display, so `list` and `get` can be pasted into an issue.
+ * @param {Record<string, unknown>} entry
+ * @returns {Record<string, unknown>}
+ */
+export function maskServerEntry(entry) {
+  /** @type {Record<string, unknown>} */
+  const out = {};
+  for (const [key, value] of Object.entries(entry)) {
+    if ((key === "env" || key === "headers") && value && typeof value === "object" && !Array.isArray(value)) {
+      out[key] = Object.fromEntries(
+        Object.entries(/** @type {Record<string, unknown>} */ (value)).map(([name, item]) => [
+          name,
+          // An environment reference is the name of a variable, not its contents,
+          // so showing it is the point. Anything else is treated as a value.
+          typeof item === "string" && ENV_REFERENCE.test(item) ? item : "*****"
+        ])
+      );
+      continue;
+    }
+    out[key] = value;
+  }
+  return out;
+}

package/packages/piagent-core/mcp/mcp-session-view.js

@@ -0,0 +1,185 @@
+import { REPOSITORY_SCOPES, SCOPES, collectServers } from "./mcp-config-layers.js";
+import { approvalState } from "./mcp-approval-store.js";
+import { maskServerEntry } from "./mcp-server-entry.js";
+import { evaluateServerReadiness } from "./mcp-auth-readiness.js";
+import { CATALOG_PREREQUISITES } from "./mcp-server-catalog.js";
+
+// What the terminal CLI and the in-session `/piagent-mcp` command both show.
+//
+// The same question gets asked from two places — a shell prompt and a Pi
+// session — and two answers that disagree about whether a server is usable is
+// worse than either answer alone. So the reading, the states and the wording
+// live here once, and both surfaces print what this returns.
+//
+// Read-only by construction: nothing here writes a config or an approval.
+
+/** @typedef {import("./mcp-auth-readiness.js").ReadinessState} ReadinessState */
+
+export class McpViewError extends Error {}
+
+/**
+ * The stdio command line, or the remote URL, shortened for a table cell.
+ * @param {Record<string, unknown>} entry
+ * @param {number} [limit]
+ * @returns {string}
+ */
+export function describeTarget(entry, limit = 56) {
+  if (typeof entry.url === "string") return entry.url;
+  const argv = [entry.command, ...(Array.isArray(entry.args) ? entry.args : [])].filter((item) => typeof item === "string");
+  const text = argv.join(" ");
+  return text.length > limit ? `${text.slice(0, limit - 3)}...` : text;
+}
+
+/**
+ * Every server visible from a project, with its readiness resolved.
+ * @param {{projectPath: string, scopes?: string[]}} options
+ */
+export function collectServerRows(options) {
+  const { projectPath, scopes } = options;
+  if (scopes) {
+    for (const scope of scopes) {
+      if (!SCOPES.includes(scope)) throw new McpViewError(`unsupported scope: ${scope}`);
+    }
+  }
+  return collectServers({ projectPath, scopes }).map((server) => ({
+    ...server,
+    transport: typeof server.entry.url === "string" ? "http" : "stdio",
+    target: describeTarget(server.entry),
+    readiness: evaluateServerReadiness(server, { projectPath })
+  }));
+}
+
+/**
+ * Servers that will not answer a tool call. `oauth` is excluded: it may already
+ * be signed in, and this cannot tell.
+ * @param {ReturnType<typeof collectServerRows>} rows
+ */
+export function blockedRows(rows) {
+  return rows.filter((row) => row.readiness.state !== "ready" && row.readiness.state !== "oauth");
+}
+
+/**
+ * One named server, resolved to a single scope. `listHint` is the caller's own
+ * way of listing servers, so the error names a command the reader can actually
+ * run from where they are.
+ *
+ * @param {{projectPath: string, name: string, scope?: string, listHint?: string, scopeHint?: string}} options
+ */
+export function describeServer(options) {
+  const { projectPath, name, scope, listHint, scopeHint = "--scope" } = options;
+  const matches = collectServerRows({ projectPath, scopes: scope ? [scope] : undefined })
+    .filter((row) => row.name === name);
+  if (matches.length === 0) {
+    throw new McpViewError(scope
+      ? `no server named ${name} in ${scope} scope`
+      : `no server named ${name}.${listHint ? ` Run \`${listHint}\` to see what is configured.` : ""}`);
+  }
+  if (matches.length > 1) {
+    throw new McpViewError(
+      `${name} is defined in more than one scope (${matches.map((row) => row.scope).join(", ")}). ` +
+      `Pass ${scopeHint} to say which one.`
+    );
+  }
+  const row = matches[0];
+  const approval = REPOSITORY_SCOPES.has(row.scope)
+    ? approvalState({ projectPath, name, entry: row.entry })
+    : undefined;
+  return { ...row, masked: maskServerEntry(row.entry), approval };
+}
+
+/**
+ * Readiness remedies are written as terminal commands, because that is where
+ * every one of them can be run. Inside a session the same step is a slash
+ * command, and telling a reader to shell out for something they can do where
+ * they are standing is how a surface ends up feeling harder than it is.
+ *
+ * @param {string | undefined} remedy
+ * @param {boolean} inSession
+ * @returns {string | undefined}
+ */
+export function remedyFor(remedy, inSession) {
+  if (!remedy || !inSession) return remedy;
+  return remedy.replace(/(^|[\s`])piagent-mcp /g, "$1/piagent-mcp ");
+}
+
+/** Left-aligned columns sized to their contents. */
+function table(headers, rows) {
+  const widths = headers.map((header, i) => Math.max(header.length, ...rows.map((cells) => cells[i].length)));
+  const line = (cells) => cells.map((cell, i) => cell.padEnd(widths[i])).join("  ").trimEnd();
+  return [line(headers), ...rows.map(line)].join("\n");
+}
+
+/**
+ * @param {ReturnType<typeof collectServerRows>} rows
+ * @returns {string}
+ */
+export function formatServerTable(rows) {
+  if (rows.length === 0) return "";
+  return table(
+    ["NAME", "SCOPE", "TRANSPORT", "TARGET", "STATE"],
+    rows.map((row) => [row.name, row.scope, row.transport, row.target, row.readiness.state])
+  );
+}
+
+/** Fields worth showing; the rest of an entry is noise in a status view. */
+const DETAIL_FIELDS = ["url", "command", "args", "env", "headers", "auth", "bearerTokenEnvVar"];
+
+/**
+ * @param {ReturnType<typeof describeServer>} detail
+ * @param {{inSession?: boolean}} [options]
+ * @returns {string[]}
+ */
+export function formatServerDetail(detail, options = {}) {
+  const lines = [
+    detail.name,
+    `  scope: ${detail.scope}`,
+    `  file: ${detail.file}`,
+    `  transport: ${detail.transport}`
+  ];
+  for (const key of DETAIL_FIELDS) {
+    const item = detail.masked[key];
+    if (item === undefined) continue;
+    lines.push(`  ${key}: ${typeof item === "string" ? item : JSON.stringify(item)}`);
+  }
+  lines.push(`  state: ${detail.readiness.state} (${detail.readiness.detail})`);
+  const next = remedyFor(detail.readiness.remedy, options.inSession === true);
+  if (next) lines.push(`  next: ${next}`);
+  if (detail.approval) lines.push(`  approval: ${detail.approval.state} (${detail.approval.digest})`);
+  return lines;
+}
+
+/**
+ * The readiness report, one line per server plus the remedy for anything stuck.
+ * `dockerRunning` is passed in rather than probed: the probe spawns a process
+ * and only the caller knows whether it can afford that.
+ *
+ * @param {ReturnType<typeof collectServerRows>} rows
+ * @param {{dockerRunning?: boolean, rerun?: string, inSession?: boolean}} [options]
+ * @returns {{lines: string[], problems: number}}
+ */
+export function formatDoctorReport(rows, options = {}) {
+  if (rows.length === 0) return { lines: ["No MCP servers configured."], problems: 0 };
+
+  const lines = [];
+  let problems = 0;
+  for (const row of rows) {
+    const usable = row.readiness.state === "ready" || row.readiness.state === "oauth";
+    if (!usable) problems += 1;
+    lines.push(`${usable ? "OK  " : "NEED"} ${row.name} (${row.scope}): ${row.readiness.detail}`);
+    const remedy = remedyFor(row.readiness.remedy, options.inSession === true);
+    if (remedy) lines.push(`       -> ${remedy}`);
+  }
+  if (options.dockerRunning === false) {
+    problems += 1;
+    lines.push("NEED docker: installed but the daemon is not responding");
+    lines.push(`       -> start Docker Desktop, then re-run ${options.rerun ?? "the check"}`);
+  }
+  const prerequisites = rows.flatMap((row) => (CATALOG_PREREQUISITES[row.name] ?? []).map((item) => `  ${row.name}: ${item}`));
+  if (prerequisites.length > 0) lines.push("", "Pinned servers also expect:", ...prerequisites);
+  return { lines, problems };
+}
+
+/** True when any configured server runs through the docker CLI. */
+export function usesDocker(rows) {
+  return rows.some((row) => row.entry.command === "docker");
+}

package/packages/piagent-core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@piagent/core",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "type": "module",
   "private": true,
   "license": "MIT",
@@ -37,8 +37,12 @@
     "typebox": "1.1.38"
   },
   "peerDependenciesMeta": {
-    "@earendil-works/pi-coding-agent": { "optional": true },
-    "typebox": { "optional": true }
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "typebox": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.19.0"

package/packages/piagent-core/prompts/model-options.md

@@ -1,5 +1,5 @@
 ---
-description: Explain native Pi model selector/scope options for Codex and Claude
+description: Explain native Pi model selector/scope options across model families
 argument-hint: "[task type, budget, or provider preference]"
 ---
 
@@ -18,15 +18,15 @@ Mandatory flow:
    - `/scoped-models` for cycle scope;
    - Ctrl+P / Shift+Ctrl+P for model cycling;
    - Shift+Tab for thinking level.
-4. Include both OpenAI Codex and Claude/Anthropic options unless the user explicitly restricts provider.
-5. Do not limit the answer to one or two legacy examples. Include the current latest-family options for Codex 5.5/5.6 and Claude Sonnet/Opus/Fable where relevant.
+4. Include both model families — the OpenAI Codex models and the Anthropic Claude models — unless the user explicitly restricts the provider. Name them as model families, never as another tool.
+5. Do not limit the answer to one or two legacy examples. Include the current latest-family options: the Codex 5.5/5.6 models and the Claude Sonnet/Opus/Fable models, where relevant.
 6. If the user needs available model versions, recommend `piagent-models`, `/model`, or `pi --list-models`.
 7. Explain thinking levels as task effort, not as quality guarantee.
 8. Do not claim token/cost savings without benchmark evidence.
 
 Current latest-family catalog to consider:
 
-OpenAI Codex:
+OpenAI Codex models (provider `openai-codex`):
 
 - `openai-codex/gpt-5.3-codex-spark`
 - `openai-codex/gpt-5.4-mini`
@@ -36,7 +36,7 @@ OpenAI Codex:
 - `openai-codex/gpt-5.6-sol`
 - `openai-codex/gpt-5.6-terra`
 
-Claude/Anthropic:
+Anthropic Claude models (provider `anthropic`):
 
 - `anthropic/claude-haiku-4-5`
 - `anthropic/claude-sonnet-4-5`
@@ -50,7 +50,7 @@ Claude/Anthropic:
 
 Default selector scope seeded by setup:
 
-| Preset | OpenAI Codex | Claude/Anthropic | Use when |
+| Preset | OpenAI Codex model | Anthropic Claude model | Use when |
 |---|---|---|---|
 | Fast scout | `openai-codex/gpt-5.4-mini:low` | `anthropic/claude-haiku-4-5:low` | quick reads, simple Q&A |
 | Balanced implement | `openai-codex/gpt-5.5:medium` | `anthropic/claude-sonnet-5:medium` | normal source tasks |
@@ -63,6 +63,6 @@ Output:
 - Current model/context if available.
 - How to open/select/change model in Pi UI.
 - What `enabledModels`/scope contains.
-- Codex family options.
-- Claude family options.
+- Codex model family options.
+- Claude model family options.
 - How to inspect/re-apply model scope from terminal.