codex-xai-oauth 0.1.0 → 0.2.2

package/dist/mcp/server.js

@@ -30948,7 +30948,7 @@ var StdioServerTransport = class {
 };
 
 // src/version.ts
-var PACKAGE_VERSION = "0.1.0";
+var PACKAGE_VERSION = "0.2.2";
 
 // src/xai/constants.ts
 var XAI_BASE_URL = "https://api.x.ai/v1";
@@ -32241,7 +32241,7 @@ var Ky = class _Ky {
   }
   #getNormalizedOptions() {
     if (!this.#cachedNormalizedOptions) {
-      const { hooks, json: json2, parseJson, stringifyJson, searchParams, timeout: timeout2, totalTimeout, throwHttpErrors, fetch, ...normalizedOptions } = this.#options;
+      const { hooks, json: json2, parseJson, stringifyJson, searchParams, timeout: timeout2, totalTimeout, throwHttpErrors, fetch: fetch2, ...normalizedOptions } = this.#options;
       this.#cachedNormalizedOptions = Object.freeze(normalizedOptions);
     }
     return this.#cachedNormalizedOptions;
@@ -32309,7 +32309,7 @@ function defaultAuthPath() {
   return join(configHome(), "codex-xai-oauth", "auth.json");
 }
 function authPath() {
-  return process.env["CODEX_XAI_OAUTH_AUTH_FILE"] || defaultAuthPath();
+  return process.env["CODEX_XAI_OAUTH_AUTH_FILE"] || grokAuthPath();
 }
 function defaultGrokAuthPath() {
   return join(homedir(), ".grok", "auth.json");
@@ -32318,10 +32318,13 @@ function grokAuthPath() {
   return process.env["CODEX_XAI_OAUTH_GROK_AUTH_FILE"] || defaultGrokAuthPath();
 }
 function readStoredAuth(path = authPath()) {
+  if (path === grokAuthPath()) {
+    return readGrokStoredAuth(path) || (!process.env["CODEX_XAI_OAUTH_AUTH_FILE"] ? readPackageStoredAuth(defaultAuthPath()) : void 0);
+  }
+  return readPackageStoredAuth(path);
+}
+function readPackageStoredAuth(path) {
   if (!existsSync(path)) {
-    if (path === defaultAuthPath() && !process.env["CODEX_XAI_OAUTH_AUTH_FILE"]) {
-      return readGrokStoredAuth();
-    }
     return void 0;
   }
   try {
@@ -32350,6 +32353,9 @@ function readStoredAuth(path = authPath()) {
     throw error51;
   }
 }
+function grokEntryKey() {
+  return `${XAI_OAUTH_ISSUER}::${XAI_OAUTH_CLIENT_ID}`;
+}
 function parseGrokExpiry(value) {
   const parsed = Date.parse(value);
   return Number.isNaN(parsed) ? void 0 : parsed;
@@ -32404,9 +32410,40 @@ function readGrokStoredAuth(path = grokAuthPath()) {
   }
 }
 function writeStoredAuth(auth, path = authPath()) {
+  if (path === grokAuthPath()) {
+    writeGrokStoredAuth(auth, path);
+    return;
+  }
   mkdirSync(dirname(path), { recursive: true, mode: 448 });
   writeFileSync(path, JSON.stringify(auth, null, 2), { mode: 384 });
 }
+function readGrokAuthFile(path) {
+  if (!existsSync(path)) {
+    return {};
+  }
+  try {
+    const data = JSON.parse(readFileSync(path, "utf8"));
+    return isRecord(data) ? data : {};
+  } catch (error51) {
+    if (error51 instanceof Error) {
+      return {};
+    }
+    throw error51;
+  }
+}
+function writeGrokStoredAuth(auth, path) {
+  const data = readGrokAuthFile(path);
+  data[grokEntryKey()] = {
+    auth_mode: "oidc",
+    expires_at: new Date(auth.expires).toISOString(),
+    key: auth.access,
+    oidc_client_id: XAI_OAUTH_CLIENT_ID,
+    oidc_issuer: XAI_OAUTH_ISSUER,
+    refresh_token: auth.refresh
+  };
+  mkdirSync(dirname(path), { recursive: true, mode: 448 });
+  writeFileSync(path, JSON.stringify(data, null, 2), { mode: 384 });
+}
 function oauthExpiry(timestampSeconds) {
   return Date.now() + Number(timestampSeconds || 3600) * 1e3;
 }
@@ -32574,7 +32611,7 @@ async function resolveXaiCredentials() {
     };
   }
   throw new Error(
-    "xAI credentials not found. Run `codex-xai-oauth login --device`, set XAI_API_KEY, or configure a Codex model provider with experimental_bearer_token."
+    "xAI credentials not found. Run `codex-xai-oauth login` to write ~/.grok/auth.json, run `codex-xai-oauth login --device`, set XAI_API_KEY, or configure a Codex model provider with experimental_bearer_token."
   );
 }
 async function credentialStatus() {
@@ -32623,6 +32660,80 @@ async function xaiRequest(path, options) {
   });
 }
 
+// src/xai/image-artifacts.ts
+import { mkdir, writeFile } from "node:fs/promises";
+import { join as join3 } from "node:path";
+async function artifactImageGenerationResult(result, options) {
+  const artifacts = [];
+  const images = result.data ?? [];
+  for (let index = 0; index < images.length; index += 1) {
+    const image = images[index];
+    if (!image) {
+      continue;
+    }
+    const artifact = await imageArtifactForPayload(image, index, options);
+    if (artifact) {
+      artifacts.push(artifact);
+    }
+  }
+  return { ...result, artifacts };
+}
+async function imageArtifactForPayload(image, index, options) {
+  if (image.b64_json) {
+    const mimeType = image.mime_type ?? "image/png";
+    const path = artifactPath(options.artifactDir, index, mimeType);
+    await writeArtifact(path, Buffer.from(image.b64_json, "base64"));
+    return {
+      index,
+      mime_type: mimeType,
+      path,
+      source: "base64",
+      status: "saved"
+    };
+  }
+  if (!image.url) {
+    return void 0;
+  }
+  return downloadImageArtifact({ ...image, url: image.url }, index, options);
+}
+async function downloadImageArtifact(image, index, options) {
+  try {
+    const response = await (options.fetchImage ?? fetch)(image.url);
+    if (!response.ok) {
+      throw new Error(`download failed with status ${response.status}`);
+    }
+    const mimeType = image.mime_type ?? response.headers.get("content-type") ?? "image/png";
+    const path = artifactPath(options.artifactDir, index, mimeType);
+    await writeArtifact(path, Buffer.from(await response.arrayBuffer()));
+    return {
+      index,
+      mime_type: mimeType,
+      path,
+      source: "url",
+      status: "saved",
+      url: image.url
+    };
+  } catch (error51) {
+    return {
+      error: error51 instanceof Error ? error51.message : String(error51),
+      index,
+      source: "url",
+      status: "remote",
+      url: image.url
+    };
+  }
+}
+async function writeArtifact(path, bytes) {
+  await mkdir(join3(path, ".."), { recursive: true });
+  await writeFile(path, bytes);
+}
+function artifactPath(artifactDir, index, mimeType) {
+  return join3(artifactDir, `image-${index + 1}.${extensionForMime(mimeType)}`);
+}
+function extensionForMime(mimeType) {
+  return mimeType.includes("jpeg") || mimeType.includes("jpg") ? "jpg" : "png";
+}
+
 // src/xai/media.ts
 async function xaiImageGenerate(args) {
   const body = {
@@ -32644,6 +32755,12 @@ async function xaiImageGenerate(args) {
   const parsed = await response.json();
   return isRecord(parsed) ? parsed : {};
 }
+async function xaiImageGenerateWithArtifacts(args) {
+  const result = await xaiImageGenerate(args);
+  return artifactImageGenerationResult(result, {
+    artifactDir: args.artifactDir
+  });
+}
 async function xaiTts(args) {
   const codec2 = args.codec || args.format;
   const body = {
@@ -32838,8 +32955,22 @@ function createXaiMcpServer() {
     async () => textJson({
       auth_file: authPath(),
       grok_auth_file: grokAuthPath(),
+      legacy_auth_file: defaultAuthPath(),
+      shared_auth_store: "~/.grok/auth.json",
+      base_url: xaiBaseUrl(),
+      browser_login: "codex-xai-oauth login",
       device_login: "codex-xai-oauth login --device",
-      api_key: "Set XAI_API_KEY in the environment."
+      status: "codex-xai-oauth status",
+      doctor: "codex-xai-oauth doctor",
+      api_key: "Set XAI_API_KEY in the environment.",
+      credential_precedence: [
+        "CODEX_XAI_OAUTH_AUTH_FILE",
+        "~/.grok/auth.json",
+        "~/.config/codex-xai-oauth/auth.json",
+        "XAI_API_KEY",
+        "Codex model provider experimental_bearer_token"
+      ],
+      note: "Default OAuth login writes a shared xAI OIDC entry to ~/.grok/auth.json; this is a shared auth store, not a requirement to use a specific Grok CLI build."
     })
   );
   registerGenerationTools(server);
@@ -32897,19 +33028,34 @@ function registerMediaTools(server) {
         n: external_exports.number().int().min(1).max(10).optional(),
         resolution: external_exports.enum(["1k", "2k"]).optional(),
         response_format: external_exports.enum(["url", "b64_json"]).optional(),
-        size: external_exports.string().optional()
+        size: external_exports.string().optional(),
+        artifact_dir: external_exports.string().optional()
       })
     },
-    async ({ prompt, model, n, resolution, response_format, size }) => textJson(
-      await xaiImageGenerate({
+    async ({
+      prompt,
+      model,
+      n,
+      resolution,
+      response_format,
+      size,
+      artifact_dir
+    }) => {
+      const args = {
         prompt,
         ...model ? { model } : {},
         ...n ? { n } : {},
         ...resolution ? { resolution } : {},
         ...response_format ? { response_format } : {},
         ...size ? { size } : {}
-      })
-    )
+      };
+      return textJson(
+        artifact_dir ? await xaiImageGenerateWithArtifacts({
+          ...args,
+          artifactDir: artifact_dir
+        }) : await xaiImageGenerate(args)
+      );
+    }
   );
   server.registerTool(
     "xai_tts",

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const PACKAGE_VERSION = "0.1.0";
+export declare const PACKAGE_VERSION = "0.2.2";
 //# sourceMappingURL=version.d.ts.map

package/dist/xai/constants.d.ts

@@ -12,6 +12,6 @@ export declare const XAI_REDIRECT_PATH = "/callback";
 export declare const OPENAI_COMPAT_HOST = "127.0.0.1";
 export declare const OPENAI_COMPAT_PORT = 8787;
 export declare const REFRESH_SKEW_MS: number;
-export declare const USER_AGENT = "codex-xai-oauth/0.1.0";
+export declare const USER_AGENT = "codex-xai-oauth/0.2.2";
 export declare function xaiBaseUrl(): string;
 //# sourceMappingURL=constants.d.ts.map

package/dist/xai/image-artifacts.d.ts

@@ -0,0 +1,33 @@
+export type ImagePayload = {
+    readonly b64_json?: string;
+    readonly mime_type?: string;
+    readonly url?: string;
+};
+export type ImageGenerationWithData = {
+    readonly data?: readonly ImagePayload[];
+    readonly [key: string]: unknown;
+};
+export type SavedImageArtifact = {
+    readonly index: number;
+    readonly mime_type: string;
+    readonly path: string;
+    readonly source: "base64" | "url";
+    readonly status: "saved";
+    readonly url?: string;
+};
+export type RemoteImageArtifact = {
+    readonly error: string;
+    readonly index: number;
+    readonly source: "url";
+    readonly status: "remote";
+    readonly url: string;
+};
+export type ImageArtifact = SavedImageArtifact | RemoteImageArtifact;
+export type ImageArtifactGenerationResult = ImageGenerationWithData & {
+    readonly artifacts: readonly ImageArtifact[];
+};
+export declare function artifactImageGenerationResult(result: ImageGenerationWithData, options: {
+    readonly artifactDir: string;
+    readonly fetchImage?: (url: string) => Promise<Response>;
+}): Promise<ImageArtifactGenerationResult>;
+//# sourceMappingURL=image-artifacts.d.ts.map

package/dist/xai/index.d.ts

@@ -1,7 +1,7 @@
 export { beginOAuth, startCallbackServer } from "./browser-oauth.js";
 export { credentialStatus, resolveXaiCredentials } from "./credentials.js";
 export { beginDeviceOAuth, pollDeviceToken, requestDeviceCode, } from "./device-oauth.js";
-export { xaiImageGenerate, xaiTts, xaiVideoGenerate } from "./media.js";
+export { xaiImageGenerate, xaiImageGenerateWithArtifacts, xaiTts, xaiVideoGenerate, } from "./media.js";
 export { buildAuthorizeUrl, discoverXaiOAuth, exchangeCodeForToken, pkcePair, refreshAccessToken, storedAuthFromToken, } from "./oauth.js";
 export { xaiChatCompletions, xaiResponses } from "./responses.js";
 export { authPath, defaultAuthPath, defaultGrokAuthPath, grokAuthPath, readGrokStoredAuth, readStoredAuth, writeStoredAuth, } from "./storage.js";

package/dist/xai/media.d.ts

@@ -1,3 +1,4 @@
+import { type ImageArtifactGenerationResult } from "./image-artifacts.js";
 export declare function xaiImageGenerate(args: {
     readonly model?: string;
     readonly n?: number;
@@ -6,6 +7,15 @@ export declare function xaiImageGenerate(args: {
     readonly response_format?: "url" | "b64_json";
     readonly size?: string;
 }): Promise<Record<string, unknown>>;
+export declare function xaiImageGenerateWithArtifacts(args: {
+    readonly artifactDir: string;
+    readonly model?: string;
+    readonly n?: number;
+    readonly prompt: string;
+    readonly resolution?: "1k" | "2k";
+    readonly response_format?: "url" | "b64_json";
+    readonly size?: string;
+}): Promise<ImageArtifactGenerationResult>;
 export declare function xaiTts(args: {
     readonly bit_rate?: number;
     readonly codec?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codex-xai-oauth",
-  "version": "0.1.0",
+  "version": "0.2.2",
   "description": "Codex plugin exposing xAI/Grok OAuth and API-key tools through a local MCP server.",
   "type": "module",
   "main": "./dist/mcp/server.js",

package/skills/xai-generate-text/SKILL.md

@@ -0,0 +1,25 @@
+---
+name: xai_generate_text
+description: Use when the user asks to generate, draft, answer, rewrite, summarize, or reason with xAI/Grok text generation through xai_generate_text.
+---
+
+# xAI Generate Text
+
+Use `xai_generate_text` for text generation with Grok through xAI Responses.
+
+Preferred MCP call:
+
+```json
+{
+  "prompt": "Write a concise release note for artifact-backed image generation.",
+  "reasoning_effort": "medium"
+}
+```
+
+Options:
+
+- `prompt`: required user request.
+- `model`: optional Grok model.
+- `reasoning_effort`: `low`, `medium`, or `high`.
+
+Use `xai_web_search` instead when the user asks for current web information. Use `xai_x_search` instead when the user asks to search X/Twitter.

package/skills/xai-grok/SKILL.md

@@ -1,11 +1,20 @@
 ---
 name: xai-grok
-description: Use xAI/Grok OAuth or API-key MCP tools for text generation, web search, X search, image generation, TTS, video generation, or credential status from Codex.
+description: Use only for general codex-xai-oauth/xAI Grok plugin overview, setup orientation, or multi-tool requests when no dedicated xai_* skill is a better fit.
 ---
 
 # xAI Grok
 
-Use the bundled MCP tools when the user asks for xAI, Grok, Grok Imagine, xAI image generation, xAI web search, X search, TTS, video generation, or xAI credential status.
+Use this umbrella skill only for general plugin overview, setup orientation, or multi-tool xAI/Grok requests. For a specific tool request, prefer the dedicated skill:
+
+- `xai_status`
+- `xai_login_instructions`
+- `xai_generate_text`
+- `xai_web_search`
+- `xai_x_search`
+- `xai_image_generate`
+- `xai_tts`
+- `xai_video_generate`
 
 ## Tools
 
@@ -14,16 +23,16 @@ Use the bundled MCP tools when the user asks for xAI, Grok, Grok Imagine, xAI im
 - `xai_generate_text`: generate text with Grok through xAI Responses.
 - `xai_web_search`: answer with xAI server-side web search.
 - `xai_x_search`: answer with xAI server-side X search. Do not pass both allowed and excluded handles.
-- `xai_image_generate`: generate images with xAI `/images/generations`.
+- `xai_image_generate`: generate images with xAI `/images/generations`. Pass `artifact_dir` when the user wants local files; URL and `b64_json` images are saved there and returned in `artifacts`.
 - `xai_tts`: generate speech audio.
 - `xai_video_generate`: generate video.
 
 ## Credential Rules
 
-- Prefer existing OAuth credentials in `~/.config/codex-xai-oauth/auth.json`.
-- If package OAuth credentials are absent, use the Grok CLI OIDC session in `~/.grok/auth.json`.
-- `CODEX_XAI_OAUTH_AUTH_FILE` overrides the auth-file path.
-- `CODEX_XAI_OAUTH_GROK_AUTH_FILE` overrides the Grok CLI auth-file path.
+- Prefer the shared xAI OIDC auth store at `~/.grok/auth.json`. It is a shared auth file, not a requirement to use a specific Grok CLI build.
+- `CODEX_XAI_OAUTH_AUTH_FILE` overrides the auth-file path with a package-format OAuth file.
+- `CODEX_XAI_OAUTH_GROK_AUTH_FILE` overrides the shared xAI OIDC auth-file path.
+- Legacy package OAuth credentials at `~/.config/codex-xai-oauth/auth.json` are read only when the shared store is absent.
 - `XAI_API_KEY` is the fallback credential.
 - `XAI_BASE_URL` can override the API base URL.
 - Do not print, quote, summarize, or store access tokens, refresh tokens, or API keys in chat.
@@ -47,3 +56,46 @@ To check status:
 ```bash
 codex-xai-oauth status
 ```
+
+## Image Generation
+
+Use `xai_image_generate` when the user asks to generate an image, Grok Imagine image, or xAI image. Defaults are `model: grok-imagine-image`, `response_format: url`, and `n: 1`.
+
+Preferred MCP call:
+
+```json
+{
+  "prompt": "tiny minimalist blue dot icon on white background",
+  "resolution": "2k",
+  "artifact_dir": ".codex-xai-artifacts"
+}
+```
+
+Direct CLI equivalent:
+
+```bash
+codex-xai-oauth image \
+  --prompt "tiny minimalist blue dot icon on white background" \
+  --resolution 2k \
+  --artifact-dir .codex-xai-artifacts
+```
+
+For base64 image payloads saved locally:
+
+```bash
+codex-xai-oauth image \
+  --prompt "a cinematic robot reading a book" \
+  --response-format b64_json \
+  --artifact-dir .codex-xai-artifacts
+```
+
+Supported image options:
+
+- `prompt`: required image prompt.
+- `n`: number of images.
+- `resolution`: `1k` or `2k`.
+- `response_format`: `url` or `b64_json`.
+- `size`: provider-specific size string.
+- `artifact_dir`: local directory for saved image artifacts.
+
+When `artifact_dir` is provided, return both the upstream JSON and the `artifacts` metadata. Each saved artifact includes a local `path`, `mime_type`, `source`, and `status`. If a remote URL cannot be downloaded, preserve the upstream `url` with `status: remote` instead of hiding it.

package/skills/xai-image-generate/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: xai_image_generate
+description: Use when the user asks to generate, create, make, or save images with xAI, Grok Imagine, xai_image_generate, or codex-xai-oauth image artifacts.
+---
+
+# xAI Image Generate
+
+Use `xai_image_generate` for xAI/Grok Imagine image requests.
+
+## Preferred MCP Call
+
+```json
+{
+  "prompt": "tiny minimalist blue dot icon on white background",
+  "resolution": "2k",
+  "artifact_dir": ".codex-xai-artifacts"
+}
+```
+
+## CLI Equivalent
+
+```bash
+codex-xai-oauth image \
+  --prompt "tiny minimalist blue dot icon on white background" \
+  --resolution 2k \
+  --artifact-dir .codex-xai-artifacts
+```
+
+For base64 image payloads saved locally:
+
+```bash
+codex-xai-oauth image \
+  --prompt "a cinematic robot reading a book" \
+  --response-format b64_json \
+  --artifact-dir .codex-xai-artifacts
+```
+
+## Options
+
+- `prompt`: required image prompt.
+- `model`: defaults to `grok-imagine-image`.
+- `n`: number of images.
+- `resolution`: `1k` or `2k`.
+- `response_format`: `url` or `b64_json`.
+- `size`: provider-specific size string.
+- `artifact_dir`: local directory for saved image artifacts.
+
+When `artifact_dir` is present, return the upstream JSON plus `artifacts`. Saved artifacts include `path`, `mime_type`, `source`, and `status`. If a remote URL cannot be downloaded, preserve its upstream `url` with `status: remote`.
+
+## Credential Safety
+
+Use existing credentials. If credentials are missing, ask the user to run:
+
+```bash
+codex-xai-oauth login --device
+```
+
+or set `XAI_API_KEY`. Never print or expose OAuth tokens or API keys.

package/skills/xai-login-instructions/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: xai_login_instructions
+description: Use when the user asks how to log in, authenticate, configure OAuth, set up XAI_API_KEY, or fix missing xAI/Grok credentials for codex-xai-oauth.
+---
+
+# xAI Login Instructions
+
+Use `xai_login_instructions` when the user needs setup commands or auth-file paths.
+
+Default OAuth login writes a shared xAI OIDC entry to `~/.grok/auth.json`. This is a shared auth store, not a requirement to use a specific Grok CLI build.
+
+For browser login:
+
+```bash
+codex-xai-oauth login
+```
+
+For OAuth device login:
+
+```bash
+codex-xai-oauth login --device
+```
+
+For API-key fallback:
+
+```bash
+export XAI_API_KEY=xai-...
+```
+
+Credential safety:
+
+- Do not expose token material.
+- Prefer `~/.grok/auth.json` unless `CODEX_XAI_OAUTH_AUTH_FILE` is explicitly set.
+- Treat `~/.config/codex-xai-oauth/auth.json` as a legacy fallback.
+- Mention `XAI_API_KEY` only as an environment variable name, never as a value.

package/skills/xai-status/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: xai_status
+description: Use when the user asks to check xAI, Grok, codex-xai-oauth, OAuth, API-key, or credential status without exposing secrets.
+---
+
+# xAI Status
+
+Use `xai_status` to check whether xAI credentials are available.
+
+Return a concise status summary. Never print, quote, or expose OAuth tokens, refresh tokens, bearer tokens, or API keys.
+
+CLI equivalent:
+
+```bash
+codex-xai-oauth status
+```

package/skills/xai-tts/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: xai_tts
+description: Use when the user asks to generate speech, text-to-speech, audio narration, voice output, or TTS with xAI/Grok through xai_tts.
+---
+
+# xAI TTS
+
+Use `xai_tts` to generate speech audio.
+
+Preferred MCP call:
+
+```json
+{
+  "input": "Hello from Grok.",
+  "voice_id": "eve",
+  "language": "auto",
+  "codec": "mp3"
+}
+```
+
+Options:
+
+- `input`: required text to speak.
+- `voice_id`: optional voice, default `eve`.
+- `language`: optional language, default `auto`.
+- `codec`: optional output codec.
+
+Return the content type and explain that the audio bytes are returned as base64 in the tool output.

package/skills/xai-video-generate/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: xai_video_generate
+description: Use when the user asks to generate video, Grok Imagine video, text-to-video, image-to-video, or xAI video through xai_video_generate.
+---
+
+# xAI Video Generate
+
+Use `xai_video_generate` for Grok Imagine video generation.
+
+Preferred text-to-video MCP call:
+
+```json
+{
+  "prompt": "A serene mountain lake at sunrise with slow camera pan, cinematic lighting"
+}
+```
+
+Image-to-video MCP call:
+
+```json
+{
+  "prompt": "Animate this image with a slow camera push-in",
+  "image_url": "https://example.com/start-frame.jpg"
+}
+```
+
+Reference-image MCP call:
+
+```json
+{
+  "prompt": "Create a short cinematic shot using these reference images for style consistency",
+  "reference_image_urls": [
+    "https://example.com/reference-1.jpg",
+    "https://example.com/reference-2.jpg"
+  ]
+}
+```
+
+Options:
+
+- `prompt`: required video prompt.
+- `image_url`: optional starting image for image-to-video.
+- `reference_image_urls`: optional array of up to 7 reference images.

package/skills/xai-web-search/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: xai_web_search
+description: Use when the user asks xAI/Grok to search the web, find current information, answer with citations, or use server-side web_search.
+---
+
+# xAI Web Search
+
+Use `xai_web_search` for web-backed answers through xAI Responses server-side `web_search`.
+
+Preferred MCP call:
+
+```json
+{
+  "prompt": "Find the latest xAI model announcement and summarize it with citations."
+}
+```
+
+Options:
+
+- `prompt`: required search question.
+- `model`: optional Grok model.
+
+Return a concise answer and include citations from the tool output when available.