@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/content/flowchart-svg/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/content/flowchart-svg/scripts/export_png.sh

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+if [ "$#" -ne 2 ]; then
+  echo "Usage: export_png.sh input.svg output.png" >&2
+  exit 2
+fi
+rsvg-convert -w 2400 -f png "$1" -o "$2"
+echo "$2"

package/skills/content/image-gen/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 1AboveIO

package/skills/content/image-gen/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: image-gen
+description: Generate an image from a text prompt with OpenAI gpt-image-2 or Google Nano Banana (Gemini), saved to an image file. Use whenever the user asks to generate, create, make, draw, paint, render, or design an image, picture, illustration, photo, artwork, logo, icon, avatar, banner, hero image, thumbnail, poster, wallpaper, sticker, or concept art — including phrasings like "an image of X", "a picture of X", "show me what X would look like", or a request for a visual for a slide, blog post, README, or social post. Also triggers on Chinese phrasings such as 生成图片, 画一张图, 做一张海报, 设计一个 logo. NOT for charts or data visualizations (dataviz), flowcharts or architecture diagrams (flowchart-svg), or editing an existing image file.
+release-version: 0.36.0
+---
+**Updates:** Once/session run `node <skill-base-dir>/release-check.mjs`.
+# Image Generation
+
+Text prompt in, image file on disk out. Two providers: **OpenAI gpt-image-2** (default)
+and **Google Nano Banana** (Gemini).
+
+## Run it
+
+```bash
+node <SKILL_ROOT>/scripts/generate.mjs "your image prompt here"
+```
+
+The script prints the endpoint it used, then the saved path. Defaults: `openai`
+provider, `gpt-image-2`, `1024x1024`, output `./generated-{timestamp}.png`.
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--provider` | `openai` | `openai` or `gemini` |
+| `--model` | provider-specific | Model name (see Models below) |
+| `--size` | provider default | OpenAI: `1024x1024`, `1536x1024`, `1024x1536`, `auto`. Gemini: `WxH` or an aspect ratio |
+| `--quality` | `auto` | `low`, `medium`, `high`, `auto` — **OpenAI only**, warned and ignored for Gemini |
+| `--output` | `./generated-{timestamp}.{ext}` | Output file path; parent dirs are created |
+
+Both `--flag value` and `--flag=value` work. An unknown flag is an error rather
+than a silent no-op — a dropped `--qualtiy` produces an image at the wrong setting
+with no hint of why, so the script names the typo and suggests the real flag.
+
+### Size on Gemini
+
+Gemini takes an aspect **ratio**, not pixel dimensions, so `--size` accepts either
+form and a `WxH` value is snapped to the closest ratio the API supports:
+
+| You pass | Gemini receives |
+|----------|-----------------|
+| `1536x1024` | `3:2` |
+| `1920x1080` | `16:9` |
+| `16:9` | `16:9` (passed straight through) |
+| omitted or `auto` | nothing — the model's own default |
+
+Supported ratios are `1:1`, `1:4`, `1:8`, `2:3`, `3:2`, `3:4`, `4:1`, `4:3`,
+`4:5`, `5:4`, `8:1`, `9:16`, `16:9`, `21:9`. A snap is printed when it happens, so
+the ratio you got is never a silent substitution.
+
+### Output format
+
+The saved extension follows the bytes the provider actually returned, so a JPEG
+never lands in a `.png`. An explicit `--output` is always honored — overriding
+your chosen path would be worse — but a mismatch prints a warning, since some
+viewers and upload validators reject a mislabeled file.
+
+The run prints the dimensions actually returned, and warns when they differ from
+what was asked for. Providers and proxies do not reliably honor `size`: a gateway
+under test returned 1536x1024 exactly as requested, then answered a 1024x1536
+request with 1402x1122. Trust the printed dimensions over the flag.
+
+Requests time out after 180s with a clear message rather than hanging forever on a
+stalled gateway.
+
+## Credentials
+
+**OpenAI** — resolved in this order, first match wins:
+
+| Order | Source | Key | Base URL |
+|-------|--------|-----|----------|
+| 1 | Environment | `OPENAI_API_KEY` | `OPENAI_BASE_URL`, else `https://api.openai.com/v1` |
+| 2 | pi harness config | `providers.openai.apiKey` | `providers.openai.baseUrl`, else the OpenAI default |
+| 3 | — | error, naming both sources | — |
+
+The pi config lives at `~/.pi/agent/models.json` (override the directory with
+`PI_CODING_AGENT_DIR`). It is read only when `OPENAI_API_KEY` is unset.
+
+### pi values are templates, not literals
+
+pi config values are resolved against the environment, so `apiKey` is very often
+`"$OPENAI_API_KEY"` rather than the key itself. This script applies pi's own
+grammar (`core/resolve-config-value.js`) before using a value:
+
+| Value | Resolves to |
+|-------|-------------|
+| `sk-abc` | itself — a literal |
+| `$VAR`, `${VAR}` | the environment variable; an empty variable counts as unset |
+| `https://$HOST/v1` | expansion inside surrounding text |
+| `$$` / `$!` | a literal `$` / `!` |
+| `!some command` | **not executed** — reported as unsupported, set the env var instead |
+
+If any referenced variable is unset, the value is unusable and the run stops with
+a message naming the variable. It is never sent as a bearer token verbatim.
+
+**A pi entry reading `$OPENAI_API_KEY` can never satisfy this fallback**, since
+the fallback only runs when that variable is absent — the template then resolves
+to nothing. To make the pi path usable, point it at a different variable
+(`$GAPSEE_KEY`) or store the key literally. The error message says this outright
+when it happens.
+
+**The key and base URL always come from the same source.** When the key falls back
+to pi, `OPENAI_BASE_URL` is deliberately ignored — pairing a pi key with an
+unrelated gateway would send the key somewhere it does not authenticate. The run
+banner prints which source won, so a surprising endpoint is visible immediately.
+
+**Gemini** — `GEMINI_API_KEY` only; there is no pi fallback.
+
+Custom gateways work for either style of source: trailing slashes are stripped and
+`/images/generations` is appended.
+
+## Models
+
+| Provider | Model | Best for |
+|----------|-------|----------|
+| `openai` | `gpt-image-2` (default) | General generation, prompt adherence |
+| `gemini` | `gemini-3-pro-image-preview` (default) | Nano Banana Pro — high quality, text rendering, complex prompts |
+| `gemini` | `gemini-3.1-flash-image-preview` | Nano Banana 2 — fast, good quality |
+| `gemini` | `gemini-2.5-flash-image` | Nano Banana — fastest, efficient |
+
+## Examples
+
+```bash
+# OpenAI (default)
+node <SKILL_ROOT>/scripts/generate.mjs "A serene mountain landscape at sunset"
+
+# OpenAI with options
+node <SKILL_ROOT>/scripts/generate.mjs "Logo design for a tech startup" \
+  --size 1024x1024 --quality high --output logo.png
+
+# Gemini Nano Banana Pro
+node <SKILL_ROOT>/scripts/generate.mjs "A watercolor painting of Tokyo" --provider gemini
+
+# Gemini Nano Banana 2 (faster)
+node <SKILL_ROOT>/scripts/generate.mjs "Product photo, white background" \
+  --provider gemini --model gemini-3.1-flash-image-preview
+```
+
+## Workflow
+
+1. **Clarify** — if the request is vague, ask for specifics (style, subject, mood,
+   colors, composition) before spending a generation.
+2. **Enhance** — expand the user's words into a full prompt using the recipe below.
+   Say what you added, so they can steer it.
+3. **Generate** — run the script.
+4. **Show** — read the saved image back so the user sees it inline, and give the path.
+5. **Iterate** — offer variations: different style, composition, or palette.
+
+## Writing the prompt
+
+Stack these five, in roughly this order — each one removes a decision the model
+would otherwise make for you:
+
+| Element | Examples |
+|---------|----------|
+| Subject | "a red fox curled asleep", "a ceramic coffee cup" |
+| Style | "watercolor illustration", "photorealistic", "flat vector art", "1950s screen print" |
+| Composition | "centered", "close-up", "wide angle", "bird's eye view", "rule of thirds" |
+| Lighting | "golden hour", "studio lighting", "dramatic shadows", "soft diffused light" |
+| Color | "warm tones", "monochromatic blue", "muted pastels", "high contrast" |
+
+Add the destination when it constrains the frame — "for a blog header", "square
+social avatar", "presentation slide background with room for text on the left".
+
+Pick the size to match: `1536x1024` for banners and headers, `1024x1536` for
+posters and phone wallpapers, `1024x1024` for avatars, icons, and social posts.
+
+## Troubleshooting
+
+| Symptom | Cause and fix |
+|---------|---------------|
+| `no usable OpenAI credentials` | Neither source yielded a key. The message names the config path and any unresolved `$VAR` it found. |
+| pi config has a key but is still rejected | Its value is a `$VAR` template whose variable is unset — commonly `$OPENAI_API_KEY` itself, which cannot work here (see above). |
+| `401` while the config "looks right" | Check whether an older copy of this script sent the template verbatim; the endpoint line now prints the resolved source. |
+| Requests hit an unexpected host | Check the `Endpoint:` line in the run banner — it names the winning source. An env key with a stale `OPENAI_BASE_URL` overrides the pi gateway. |
+| `401`/`403` from a custom gateway | Key and gateway are mismatched. Set both env vars together, or unset `OPENAI_API_KEY` to use the pi pair. |
+| `model not found` on a gateway | Not every proxy carries `gpt-image-2`; pass `--model`, or use `--provider gemini`. |
+| `No image data in response` | The endpoint answered but returned no image — usually a proxy that does not implement `/images/generations`. |
+| Content refusals | Rephrase away from real people, trademarks, and named living artists. |
+| Image came back the wrong shape | The provider ignored `size`. The run warns when this happens; try a different model, or crop afterwards. |
+| `429` / quota exceeded on Gemini | The key has no image quota — Gemini image models are not on the free tier. |
+
+## Tests
+
+```bash
+node --test <SKILL_ROOT>/scripts/*.test.mjs
+```
+
+`credentials.test.mjs` covers the resolution order above (env precedence, pi
+template expansion, the same-source rule, malformed and missing configs).
+`options.test.mjs` covers flag parsing, the Gemini ratio snapping, and output
+naming. Neither touches the network.

package/skills/content/image-gen/release-check.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+const WEEK_MS = 7 * DAY_MS;
+const here = dirname(fileURLToPath(import.meta.url));
+
+function readJson(path, fallback = {}) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
+}
+
+function frontmatterValue(text, key) {
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
+  const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
+  return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
+}
+
+function repositoryOf(source) {
+  const value = String(source ?? '').trim();
+  const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
+  return match?.[1] ?? null;
+}
+
+function stableVersion(value) {
+  const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
+  return match ? match.slice(1).map(Number) : null;
+}
+
+function newer(left, right) {
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return false;
+}
+
+function writeCache(path, value) {
+  try {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(value));
+  } catch { /* A read-only cache must not block skill use. */ }
+}
+
+function main(now = Date.now()) {
+  if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
+  const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
+  const name = frontmatterValue(skill, 'name');
+  const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
+  if (!name || !localVersion) return;
+
+  const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
+  const entry = lock.skills?.[name];
+  const repository = repositoryOf(entry?.sourceUrl || entry?.source);
+  if (!repository) return;
+
+  const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
+  const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
+  const all = readJson(cachePath);
+  const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
+
+  if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
+    const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      timeout: 1500,
+    });
+    cache.lastCheck = now;
+    if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
+    else delete cache.latestTag;
+    all[repository] = cache;
+    writeCache(cachePath, all);
+  }
+
+  const latestVersion = stableVersion(cache.latestTag);
+  if (!latestVersion || !newer(latestVersion, localVersion)) return;
+  if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
+
+  cache.notifiedTag = cache.latestTag;
+  cache.notifiedAt = now;
+  all[repository] = cache;
+  writeCache(cachePath, all);
+  const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
+  process.stdout.write(
+    `UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
+      + `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
+      + 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
+  );
+}
+
+try { main(); } catch { /* Update checks are advisory and always fail silent. */ }

package/skills/content/image-gen/scripts/credentials.mjs

@@ -0,0 +1,217 @@
+/**
+ * Credential resolution for the image providers.
+ *
+ * Environment variables win. When OPENAI_API_KEY is absent we fall back to the
+ * pi harness config, which stores provider entries as
+ * `providers.<name> = { baseUrl, apiKey }` in `<agent dir>/models.json`
+ * (default `~/.pi/agent`, overridable with PI_CODING_AGENT_DIR).
+ *
+ * pi config values are NOT plain literals. They are templates resolved against
+ * the environment — `$VAR`, `${VAR}`, with `$$` and `$!` escaping a literal `$`
+ * and `!`, and a leading `!` marking a shell command. A value that is not
+ * expanded is a bearer token reading `$OPENAI_API_KEY`, which authenticates
+ * against nothing. The grammar below mirrors pi's own
+ * `core/resolve-config-value.js`.
+ */
+
+import { readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const DEFAULT_OPENAI_BASE_URL = 'https://api.openai.com/v1';
+
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_NAME_PREFIX_RE = /^[A-Za-z_][A-Za-z0-9_]*/;
+
+export function piModelsPath(env = process.env) {
+  const agentDir = env.PI_CODING_AGENT_DIR || join(homedir(), '.pi', 'agent');
+  return join(agentDir, 'models.json');
+}
+
+const stripTrailingSlashes = (url) => url.replace(/\/+$/, '');
+
+function parseTemplate(config) {
+  const parts = [];
+  const appendLiteral = (value) => {
+    if (!value) return;
+    const previous = parts[parts.length - 1];
+    if (previous?.type === 'literal') previous.value += value;
+    else parts.push({ type: 'literal', value });
+  };
+
+  let index = 0;
+  while (index < config.length) {
+    const dollar = config.indexOf('$', index);
+    if (dollar < 0) {
+      appendLiteral(config.slice(index));
+      break;
+    }
+    appendLiteral(config.slice(index, dollar));
+
+    const next = config[dollar + 1];
+    if (next === '$' || next === '!') {
+      appendLiteral(next);
+      index = dollar + 2;
+      continue;
+    }
+
+    if (next === '{') {
+      const end = config.indexOf('}', dollar + 2);
+      if (end < 0) {
+        appendLiteral('$');
+        index = dollar + 1;
+        continue;
+      }
+      const name = config.slice(dollar + 2, end);
+      if (ENV_NAME_RE.test(name)) parts.push({ type: 'env', name });
+      else appendLiteral(config.slice(dollar, end + 1));
+      index = end + 1;
+      continue;
+    }
+
+    const match = config.slice(dollar + 1).match(ENV_NAME_PREFIX_RE);
+    if (match) {
+      parts.push({ type: 'env', name: match[0] });
+      index = dollar + 1 + match[0].length;
+      continue;
+    }
+
+    appendLiteral('$');
+    index = dollar + 1;
+  }
+
+  return parts;
+}
+
+/**
+ * Expand one pi config value.
+ *
+ * @returns {{value?: string, missing: string[], command?: string}}
+ *   `value` is set only when every referenced variable resolved. `missing`
+ *   names the variables that did not. `command` is set for `!shell` values,
+ *   which this script reports rather than executes.
+ */
+export function expandPiValue(raw, env = process.env) {
+  if (typeof raw !== 'string' || raw === '') return { missing: [] };
+  if (raw.startsWith('!')) return { missing: [], command: raw.slice(1) };
+
+  const missing = [];
+  let expanded = '';
+  for (const part of parseTemplate(raw)) {
+    if (part.type === 'literal') {
+      expanded += part.value;
+      continue;
+    }
+    // pi resolves with `||`, so an empty string counts as unset.
+    const value = env[part.name] || undefined;
+    if (value === undefined) {
+      if (!missing.includes(part.name)) missing.push(part.name);
+      continue;
+    }
+    expanded += value;
+  }
+
+  if (missing.length) return { missing };
+  return { value: expanded, missing: [] };
+}
+
+async function readPiProvider(name, configPath) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(configPath, 'utf8'));
+  } catch {
+    // Missing, unreadable, or malformed — no fallback available.
+    return null;
+  }
+  return parsed?.providers?.[name] ?? null;
+}
+
+const asVarList = (names) => names.map((name) => `$${name}`).join(', ');
+
+/**
+ * Resolve the OpenAI key and base URL.
+ *
+ * @returns {Promise<{ok: true, apiKey: string, baseUrl: string, source: string}
+ *   | {ok: false, reason: string}>}
+ */
+export async function resolveOpenAI({ env = process.env, configPath } = {}) {
+  if (env.OPENAI_API_KEY) {
+    return {
+      ok: true,
+      apiKey: env.OPENAI_API_KEY,
+      baseUrl: stripTrailingSlashes(env.OPENAI_BASE_URL || DEFAULT_OPENAI_BASE_URL),
+      source: 'env (OPENAI_API_KEY)',
+    };
+  }
+
+  const path = configPath || piModelsPath(env);
+  const provider = await readPiProvider('openai', path);
+  if (!provider || !provider.apiKey) {
+    return {
+      ok: false,
+      reason: `OPENAI_API_KEY is not set, and ${path} has no providers.openai.apiKey to fall back to.`,
+    };
+  }
+
+  const key = expandPiValue(provider.apiKey, env);
+  if (key.command) {
+    return {
+      ok: false,
+      reason:
+        `${path} resolves providers.openai.apiKey by running a shell command ` +
+        `(!${key.command}). This script does not execute config commands — set OPENAI_API_KEY instead.`,
+    };
+  }
+  if (!key.value) {
+    return {
+      ok: false,
+      reason:
+        `${path} sets providers.openai.apiKey to a template referencing ${asVarList(key.missing)}, ` +
+        `which ${key.missing.length > 1 ? 'are' : 'is'} not set. Note that a pi entry pointing at ` +
+        `$OPENAI_API_KEY can never satisfy this fallback: the fallback only runs when that variable ` +
+        `is absent. Point it at a different variable, or store the key literally.`,
+    };
+  }
+
+  // Key and base URL come from the same source deliberately. Pairing the pi key
+  // with an OPENAI_BASE_URL pointing at some other gateway would send the key to
+  // a service it does not authenticate against — so an unresolvable pi baseUrl
+  // fails here rather than quietly falling back to api.openai.com.
+  let baseUrl = DEFAULT_OPENAI_BASE_URL;
+  if (provider.baseUrl) {
+    const resolved = expandPiValue(provider.baseUrl, env);
+    if (resolved.command) {
+      return {
+        ok: false,
+        reason: `${path} resolves providers.openai.baseUrl by running a shell command, which this script does not execute.`,
+      };
+    }
+    if (!resolved.value) {
+      return {
+        ok: false,
+        reason: `${path} sets providers.openai.baseUrl to a template referencing ${asVarList(resolved.missing)}, which ${resolved.missing.length > 1 ? 'are' : 'is'} not set.`,
+      };
+    }
+    baseUrl = resolved.value;
+  }
+
+  return {
+    ok: true,
+    apiKey: key.value,
+    baseUrl: stripTrailingSlashes(baseUrl),
+    source: `pi config (${path})`,
+  };
+}
+
+/**
+ * Resolve the Gemini key. Env only — pi has no Gemini provider convention to
+ * fall back to.
+ *
+ * @returns {{ok: true, apiKey: string, source: string} | {ok: false, reason: string}}
+ */
+export function resolveGemini({ env = process.env } = {}) {
+  if (!env.GEMINI_API_KEY) {
+    return { ok: false, reason: 'GEMINI_API_KEY environment variable is required.' };
+  }
+  return { ok: true, apiKey: env.GEMINI_API_KEY, source: 'env (GEMINI_API_KEY)' };
+}