@ax-llm/ax 25.4.0 → 25.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-llm/ax",
-  "version": "25.4.0",
+  "version": "25.4.2",
   "type": "module",
   "description": "The best library to work with LLMs",
   "repository": {

package/scripts/postinstall.mjs

@@ -1,34 +1,15 @@
 #!/usr/bin/env node
 
-/**
- * Postinstall script for @ax-llm/ax
- *
- * Auto-installs/upgrades the Claude Code skill on package install.
- *
- * Features:
- * - Skips in CI environments (CI, CONTINUOUS_INTEGRATION env vars)
- * - Skips if AX_SKIP_SKILL_INSTALL=1
- * - Silent failure (never breaks package installation)
- * - Cross-platform (macOS, Linux, Windows)
- * - Only logs in interactive terminals (process.stdout.isTTY)
- * - Version-aware upgrades: only upgrades if newer version available
- */
-
-import {
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  writeFileSync,
-} from 'node:fs';
-import { basename, dirname, join, sep } from 'node:path';
+// Register one entry-point skill with bundled guides. Specialist skills are
+// available through the explicit setup command; package installation never
+// adds them individually. Failures must never break dependency installation.
+import { dirname, join, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { autoSkillInstallEnabled } from './skill-config.mjs';
+import { installSkills } from './skill-install.mjs';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
+const __dirname = dirname(fileURLToPath(import.meta.url));
 
-// Check if we should skip installation
 function shouldSkip() {
   // Skip in CI environments
   if (process.env.CI === 'true' || process.env.CI === '1') {
@@ -73,88 +54,6 @@ function shouldSkip() {
   return false;
 }
 
-// Check if we're in an interactive terminal
-function isInteractive() {
-  return process.stdout.isTTY === true;
-}
-
-/**
- * Compare semver versions
- * Returns: 1 if a > b, -1 if a < b, 0 if equal
- */
-function compareSemver(a, b) {
-  const parseVersion = (v) => {
-    const match = v.match(/^(\d+)\.(\d+)\.(\d+)/);
-    if (!match) return [0, 0, 0];
-    return [
-      Number.parseInt(match[1], 10),
-      Number.parseInt(match[2], 10),
-      Number.parseInt(match[3], 10),
-    ];
-  };
-
-  const [aMajor, aMinor, aPatch] = parseVersion(a);
-  const [bMajor, bMinor, bPatch] = parseVersion(b);
-
-  if (aMajor !== bMajor) return aMajor > bMajor ? 1 : -1;
-  if (aMinor !== bMinor) return aMinor > bMinor ? 1 : -1;
-  if (aPatch !== bPatch) return aPatch > bPatch ? 1 : -1;
-  return 0;
-}
-
-/**
- * Get the installed skill version from the file
- */
-function getInstalledVersion(targetPath) {
-  if (!existsSync(targetPath)) {
-    return null;
-  }
-
-  try {
-    const content = readFileSync(targetPath, 'utf8');
-    const match = content.match(/^version:\s*["']?([^"'\n\r]+)/m);
-    return match ? match[1].trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Get the skill name from YAML frontmatter, falling back to filename without .md
- */
-function getSkillName(filePath) {
-  try {
-    const content = readFileSync(filePath, 'utf8');
-    const match = content.match(/^name:\s*["']?([^"'\n\r]+)/m);
-    if (match) return match[1].trim();
-  } catch {
-    // Fall through to fallback
-  }
-  return basename(filePath, '.md');
-}
-
-/**
- * Get the package version from the skill source file
- */
-function getPackageVersion(sourcePath) {
-  if (!existsSync(sourcePath)) {
-    return null;
-  }
-
-  try {
-    const content = readFileSync(sourcePath, 'utf8');
-    const match = content.match(/^version:\s*["']?([^"'\n\r]+)/m);
-    return match ? match[1].trim() : null;
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Find the project root by using INIT_CWD (set by npm/yarn/pnpm to the
- * directory where `install` was run), falling back to finding the
- * topmost node_modules in __dirname and taking its parent.
- */
 function findProjectRoot() {
   // INIT_CWD is the most reliable — npm, yarn, and pnpm all set it
   if (process.env.INIT_CWD) {
@@ -175,105 +74,20 @@ function findProjectRoot() {
   return join(__dirname, '..', '..', '..', '..');
 }
 
-/**
- * Main installation function
- */
-function install() {
-  // Skip if needed
-  if (shouldSkip()) {
-    return;
-  }
-
+if (!shouldSkip()) {
   try {
-    // Paths
-    const skillsSourceDir = join(__dirname, '..', 'skills');
     const projectRoot = findProjectRoot();
-    const skillsBaseDir = join(projectRoot, '.claude', 'skills');
-
-    // Discover all *.md skill files
-    if (!existsSync(skillsSourceDir)) {
-      return;
-    }
-
-    const skillFiles = readdirSync(skillsSourceDir).filter((f) =>
-      f.endsWith('.md')
-    );
-
-    if (skillFiles.length === 0) {
-      return;
-    }
-
-    // Clean up legacy flat file structure (.claude/skills/ax/*.md except SKILL.md)
-    const legacyDir = join(skillsBaseDir, 'ax');
-    if (existsSync(legacyDir)) {
-      try {
-        const legacyFiles = readdirSync(legacyDir).filter(
-          (f) => f.endsWith('.md') && f !== 'SKILL.md'
-        );
-        for (const f of legacyFiles) {
-          rmSync(join(legacyDir, f), { force: true });
-        }
-      } catch {
-        // Ignore cleanup errors
-      }
-    }
-
-    const results = [];
-
-    for (const file of skillFiles) {
-      const skillSource = join(skillsSourceDir, file);
-      const skillName = getSkillName(skillSource);
-      const skillDir = join(skillsBaseDir, skillName);
-      const skillTarget = join(skillDir, 'SKILL.md');
-
-      const packageVersion = getPackageVersion(skillSource);
-      const installedVersion = getInstalledVersion(skillTarget);
-
-      let shouldInstallFile = false;
-      let action = 'Installed';
-      let versionInfo = '';
-
-      if (!existsSync(skillTarget)) {
-        shouldInstallFile = true;
-        versionInfo = packageVersion ? ` (v${packageVersion})` : '';
-      } else if (installedVersion && packageVersion) {
-        const comparison = compareSemver(packageVersion, installedVersion);
-        if (comparison > 0) {
-          shouldInstallFile = true;
-          action = 'Upgraded';
-          versionInfo = ` (v${installedVersion} \u2192 v${packageVersion})`;
-        }
-      } else if (!installedVersion && existsSync(skillTarget)) {
-        shouldInstallFile = true;
-        action = 'Upgraded';
-        versionInfo = packageVersion ? ` (v${packageVersion})` : '';
-      }
-
-      if (shouldInstallFile) {
-        if (!existsSync(skillDir)) {
-          mkdirSync(skillDir, { recursive: true });
-        }
-
-        const content = readFileSync(skillSource, 'utf8');
-        writeFileSync(skillTarget, content, 'utf8');
-        results.push({ file: skillName, action, versionInfo });
-      }
-    }
-
-    if (results.length > 0 && isInteractive()) {
-      const noun = results.length === 1 ? 'skill' : 'skills';
-      const details = results
-        .map((r) => `${r.action} ${r.file}${r.versionInfo}`)
-        .join(', ');
+    const installed = autoSkillInstallEnabled(projectRoot)
+      ? installSkills(join(__dirname, '..'), projectRoot, {
+          upgradeInstalled: true,
+        })
+      : [];
+    if (installed.length > 0 && process.stdout.isTTY) {
       console.log(
-        `\u2713 ${results.length} Ax Claude Code ${noun}: ${details}`
+        '✓ Ax skills updated; entry point includes local reference guides.'
       );
     }
   } catch {
-    // Silent failure - never break npm install
-    // The CLI command can be used for manual installation
+    // Manual recovery: npx @ax-llm/ax setup-claude
   }
 }
-
-// Run installation
-install();

package/scripts/skill-bundles.mjs

@@ -0,0 +1,70 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export function parseSkillFrontmatter(markdown) {
+  const text = markdown.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/)?.[1];
+  if (!text) return {};
+  const field = (key) =>
+    text.match(new RegExp(`^${key}:\\s*["']?(.+?)["']?\\s*$`, 'm'))?.[1];
+  return {
+    name: field('name'),
+    description: field('description'),
+    version: field('version'),
+  };
+}
+
+export function stripSkillFrontmatter(markdown) {
+  return markdown.replace(/^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)(?:\r?\n)*/, '');
+}
+
+// The source docs remain independently installable. The entry point bundles
+// those same docs as ordinary references, so only one skill needs registering.
+export function readTypeScriptSkillBundles(skillsRoot, version) {
+  const sources = readdirSync(skillsRoot)
+    .filter((file) => file.endsWith('.md'))
+    .sort()
+    .map((file) => {
+      const content = readFileSync(join(skillsRoot, file), 'utf8').replace(
+        /^version:\s*["']?__VERSION__["']?/m,
+        `version: "${version}"`
+      );
+      const metadata = parseSkillFrontmatter(content);
+      if (!metadata.name || !metadata.description) {
+        throw new Error(`${file} is missing skill name or description`);
+      }
+      return { ...metadata, file, content };
+    });
+  const byFile = new Map(sources.map((skill) => [skill.file, skill]));
+  return sources.map((skill) => {
+    const files = {};
+    const addReference = (file) => {
+      const key = `references/${file}`;
+      if (files[key]) return;
+      const source = byFile.get(file);
+      if (!source) throw new Error(`Missing skill reference: ${file}`);
+      files[key] = stripSkillFrontmatter(source.content);
+      for (const match of files[key].matchAll(
+        /\]\((ax-[\w-]+\.md)(?:#[^)]*)?\)/g
+      )) {
+        addReference(match[1]);
+      }
+    };
+    const content = skill.content.replace(
+      /\]\((ax-[\w-]+\.md)((?:#[^)]*)?)\)/g,
+      (_, file, anchor) => {
+        addReference(file);
+        return `](references/${file}${anchor})`;
+      }
+    );
+    if (skill.name === 'ax-llm') {
+      for (const source of sources) {
+        if (source.name !== skill.name) addReference(source.file);
+      }
+      files['references/quickstart.md'] = readFileSync(
+        join(skillsRoot, 'references', 'quickstart.md'),
+        'utf8'
+      );
+    }
+    return { ...skill, content, files: { 'SKILL.md': content, ...files } };
+  });
+}

package/scripts/skill-config.mjs

@@ -0,0 +1,59 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+function isObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function readProjectConfig(projectRoot) {
+  const file = join(projectRoot, 'package.json');
+  const source = readFileSync(file, 'utf8');
+  const config = JSON.parse(source);
+  if (
+    !isObject(config) ||
+    ('ax' in config && !isObject(config.ax)) ||
+    (config.ax && 'skills' in config.ax && !isObject(config.ax.skills)) ||
+    (config.ax?.skills &&
+      'autoInstall' in config.ax.skills &&
+      typeof config.ax.skills.autoInstall !== 'boolean')
+  )
+    throw new Error(
+      'Expected package.json ax.skills.autoInstall to be a boolean within ax and skills objects.'
+    );
+  return { file, source, config };
+}
+
+export function autoSkillInstallEnabled(projectRoot) {
+  try {
+    return (
+      readProjectConfig(projectRoot).config.ax?.skills?.autoInstall !== false
+    );
+  } catch (error) {
+    if (error.code === 'ENOENT') return true;
+    throw error;
+  }
+}
+
+export function setAutoSkillInstall(projectRoot, enabled) {
+  let project;
+  try {
+    project = readProjectConfig(projectRoot);
+  } catch (error) {
+    if (error.code === 'ENOENT')
+      throw new Error(
+        'No package.json found. Run this command from your project root.'
+      );
+    throw error;
+  }
+  const { file, source, config } = project;
+  config.ax ??= {};
+  config.ax.skills ??= {};
+  config.ax.skills.autoInstall = enabled;
+  const indent = source.match(/^[\t ]+(?=")/m)?.[0] ?? 2;
+  const newline = source.includes('\r\n') ? '\r\n' : '\n';
+  const content = JSON.stringify(config, null, indent).replaceAll(
+    '\n',
+    newline
+  );
+  writeFileSync(file, content + (source.endsWith('\n') ? newline : ''), 'utf8');
+}

package/scripts/skill-install.mjs

@@ -0,0 +1,123 @@
+import {
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { dirname, join } from 'node:path';
+import {
+  parseSkillFrontmatter,
+  readTypeScriptSkillBundles,
+} from './skill-bundles.mjs';
+
+function packageSkills(packageRoot) {
+  const { version } = JSON.parse(
+    readFileSync(join(packageRoot, 'package.json'), 'utf8')
+  );
+  return readTypeScriptSkillBundles(join(packageRoot, 'skills'), version);
+}
+
+function compareVersions(a, b) {
+  const parts = (value) =>
+    value
+      .match(/^(\d+)\.(\d+)\.(\d+)/)
+      ?.slice(1)
+      .map(Number) ?? [0, 0, 0];
+  const left = parts(a);
+  const right = parts(b);
+  for (let i = 0; i < 3; i++) {
+    if (left[i] !== right[i]) return left[i] > right[i] ? 1 : -1;
+  }
+  return 0;
+}
+
+export function installSkills(
+  packageRoot,
+  projectRoot,
+  { all = false, names = [], force = false, upgradeInstalled = false } = {}
+) {
+  const skills = packageSkills(packageRoot);
+  const selectedNames = all
+    ? skills.map((skill) => skill.name)
+    : names.length
+      ? names
+      : ['ax-llm'];
+  if (upgradeInstalled) {
+    for (const skill of skills) {
+      if (
+        existsSync(
+          join(projectRoot, '.claude', 'skills', skill.name, 'SKILL.md')
+        ) &&
+        !selectedNames.includes(skill.name)
+      ) {
+        selectedNames.push(skill.name);
+      }
+    }
+  }
+  for (const name of selectedNames) {
+    if (!skills.some((skill) => skill.name === name))
+      throw new Error(`Unknown Ax skill: ${name}`);
+  }
+  const results = [];
+  // Keep the default entry point ahead of optional upgrades, so a broken
+  // specialist folder cannot prevent the main capability index installing.
+  for (const name of new Set(selectedNames)) {
+    const skill = skills.find((entry) => entry.name === name);
+    const dir = join(projectRoot, '.claude', 'skills', skill.name);
+    const target = join(dir, 'SKILL.md');
+    const installed = existsSync(target)
+      ? parseSkillFrontmatter(readFileSync(target, 'utf8')).version
+      : undefined;
+    const comparison = installed
+      ? compareVersions(skill.version, installed)
+      : 1;
+    // Refresh equal-version legacy installs which predate bundled references.
+    const missingFiles = Object.keys(skill.files).some(
+      (file) => !existsSync(join(dir, file))
+    );
+    if (!force && (comparison < 0 || (comparison === 0 && !missingFiles)))
+      continue;
+    for (const [file, content] of Object.entries(skill.files)) {
+      if (file === 'SKILL.md') continue;
+      const dest = join(dir, file);
+      mkdirSync(dirname(dest), { recursive: true });
+      writeFileSync(dest, content, 'utf8');
+    }
+    // Register the skill only after every guide was successfully written.
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(target, skill.content, 'utf8');
+    results.push(skill.name);
+  }
+  return results;
+}
+
+// Remove only package-defined files, preserving unrelated files in skill folders.
+export function removeSkills(packageRoot, projectRoot) {
+  const skills = packageSkills(packageRoot);
+  const base = join(projectRoot, '.claude', 'skills');
+  let removed = 0;
+  for (const skill of skills) {
+    const dir = join(base, skill.name);
+    if (existsSync(join(dir, 'SKILL.md'))) removed++;
+    for (const file of Object.keys(skill.files))
+      rmSync(join(dir, file), { force: true });
+    for (const folder of ['references', '']) {
+      try {
+        rmdirSync(join(dir, folder));
+      } catch {
+        /* Keep nonempty folders. */
+      }
+    }
+  }
+  const legacy = join(base, 'ax');
+  if (existsSync(legacy)) {
+    for (const file of readdirSync(legacy)) {
+      if (skills.some((skill) => skill.file === file))
+        rmSync(join(legacy, file), { force: true });
+    }
+  }
+  return removed;
+}

package/skills/ax-agent-context.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-context
 description: This skill helps an LLM pick the right AxAgent context tool for a job - contextMap for recurring corpora, contextPolicy presets for within-run trajectory compaction, agent.optimize for offline GEPA instruction/demo tuning, agent.playbook for an evolving context playbook (offline evolve + online update), and recall/memories + skills for per-turn retrieval. Use when the user asks "which context feature should I use", confuses contextMap with contextPolicy or memory, or wants a decision guide for long-context agents. For contextPolicy/contextMap codegen use ax-agent-rlm; for recall/skills use ax-agent-memory-skills; for agent.optimize or agent.playbook use ax-agent-optimize.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AxAgent Context Selection (@ax-llm/ax)

package/skills/ax-agent-memory-skills.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-memory-skills
 description: This skill helps an LLM generate correct AxAgent memory retrieval, context-map, and dynamic skill-loading code using @ax-llm/ax. Use when the user asks about contextMap, AxAgentContextMap, onMemoriesSearch, memoriesCatalog, recall(...), inputs.memories, onLoadedMemories, onUsedMemories, onSkillsSearch, skillsCatalog, AxAgentCatalogSkill, discover({ skills }), onLoadedSkills, onUsedSkills, preloaded skills, preloading memories at forward time, relevanceRanking hints, loaded memory/skill IDs, or carrying memories across forward() calls.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AxAgent Memory And Skills Rules (@ax-llm/ax)

package/skills/ax-agent-observability.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-observability
 description: This skill helps an LLM generate correct AxAgent observability code using @ax-llm/ax. Use when the user asks about axGlobals.onUsage, usageContext, centralized or multi-tenant usage accounting, actorTurnCallback, onContextEvent, agentStatusCallback, onFunctionCall, reportSuccess, reportFailure, getChatLog(), getUsage(), resetUsage(), debug traces, progress updates, or telemetry for AxAgent runs.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AxAgent Observability Rules (@ax-llm/ax)

package/skills/ax-agent-optimize.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-optimize
 description: This skill helps an LLM generate correct AxAgent tuning and evaluation code using @ax-llm/ax. Use when the user asks about agent.optimize(...), judgeOptions, eval datasets, optimization targets, saved optimizedProgram artifacts, or agent optimization guidance.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AxAgent Optimize Codegen Rules (@ax-llm/ax)

package/skills/ax-agent-rlm.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent-rlm
 description: This skill helps an LLM generate correct AxAgent RLM/runtime code using @ax-llm/ax. Use when the user asks about RLM code execution, AxJSRuntime, contextFields, contextPolicy, liveRuntimeState, promptLevel, stage prompt controls, executorModelPolicy, maxRuntimeChars, agent.test(...), llmQuery(...), recursionOptions, or long-running agent runtime behavior.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AxAgent RLM Runtime Rules (@ax-llm/ax)

package/skills/ax-agent.md

@@ -1,7 +1,7 @@
 ---
 name: ax-agent
 description: This skill helps an LLM generate correct core AxAgent code using @ax-llm/ax. Use when the user asks about agent(), child agents, namespaced functions, discovery mode, clarification, bubbleErrors, host-side final/clarification protocol, or ordinary agent runtime behavior. For MCP clients, native runtime modules, subscriptions, tasks, or authentication use ax-mcp alongside this skill. For RLM/code-runtime work use ax-agent-rlm; for callbacks and telemetry use ax-agent-observability; for recall/memory/skill loading use ax-agent-memory-skills; for agent.optimize(...) use ax-agent-optimize.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AxAgent Codegen Rules (@ax-llm/ax)

package/skills/ax-ai.md

@@ -1,7 +1,7 @@
 ---
 name: ax-ai
 description: This skill helps an LLM generate correct AI provider setup and configuration code using @ax-llm/ax. Use when the user asks about ai(), providers, models, routing, adaptive balancing, presets, embeddings, batch audio with ai.transcribe() or ai.speak(), extended thinking, context caching, or mentions OpenAI/Anthropic/Google/Azure/DeepSeek/Meta/Mistral/Cohere/Reka/Grok/Typesafe/Jev with @ax-llm/ax.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AI Provider Codegen Rules (@ax-llm/ax)

package/skills/ax-audio.md

@@ -1,7 +1,7 @@
 ---
 name: ax-audio
 description: This skill helps an LLM generate correct audio code with @ax-llm/ax. Use when the user asks about ai.transcribe(), ai.speak(), signature audio inputs or outputs, agent audio behavior, .chat() conversational audio, OpenAI audio or realtime models, Gemini Live native audio, Grok Voice Agent models, voices, formats, transcripts, or how audio fits with structured outputs.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # Audio I/O Codegen Rules (@ax-llm/ax)

package/skills/ax-flow.md

@@ -1,7 +1,7 @@
 ---
 name: ax-flow
 description: This skill helps an LLM generate correct AxFlow workflow code using @ax-llm/ax. Use when the user asks about flow(), AxFlow, workflow orchestration, parallel execution, DAG workflows, conditional routing, map/reduce patterns, or multi-node AI pipelines.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AxFlow Codegen Rules (@ax-llm/ax)

package/skills/ax-gen.md

@@ -1,7 +1,7 @@
 ---
 name: ax-gen
 description: This skill helps an LLM generate correct AxGen code using @ax-llm/ax. Use when the user asks about ax(), AxGen, generators, forward(), streamingForward(), validation, assertions, streaming assertions, field processors, step hooks, self-tuning, or structured outputs. For MCP clients, transports, prompts, resources, tasks, subscriptions, or authentication use ax-mcp alongside this skill.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # AxGen Codegen Rules (@ax-llm/ax)

package/skills/ax-gepa.md

@@ -1,7 +1,7 @@
 ---
 name: ax-gepa
 description: This skill helps an LLM generate correct AxGEPA optimization code using @ax-llm/ax. Use when the user asks about AxGEPA, GEPA, Pareto optimization, multi-objective prompt tuning, reflective prompt evolution, validationExamples, maxMetricCalls, or optimizing a generator, flow, or agent tree.
-version: "25.4.0"
+version: "25.4.2"
 ---
 
 # GEPA Optimization Codegen Rules (@ax-llm/ax)