@sanity/ailf 3.6.0 → 3.8.0

package/dist/cli.js

@@ -13,7 +13,7 @@
  * appends Quick Start examples.
  *
  * Usage:
- *   ailf pipeline [flags]       # full evaluation pipeline
+ *   ailf run [flags]            # full evaluation run
  *   ailf compare [flags]        # compare evaluation runs
  *   ailf baseline <cmd> [flags] # baseline management
  *   ailf validate [flags]       # config validation
@@ -26,7 +26,7 @@
  *   --dotenv <path>             # override default .env path
  *
  * Dev mode (without building):
- *   tsx src/cli.ts pipeline --debug
+ *   tsx src/cli.ts run --debug
  */
 import { config as dotenvConfig } from "dotenv";
 import { existsSync, readFileSync } from "fs";
@@ -76,22 +76,75 @@ else if (process.argv.includes("--quiet") || process.argv.includes("-q")) {
     process.env.AILF_LOG_LEVEL = "quiet";
 }
 // ---------------------------------------------------------------------------
-// W0052 — hard-error on retired capture flags and env vars.
-// --------------------------------------------------------------------------
-// The legacy collector has been removed. Callers still using
-// --capture / --capture-dir / --no-capture-compress / --no-capture-extras
-// or AILF_CAPTURE* / AILF_LEGACY_COLLECTOR / AILF_UNIFIED_ARTIFACTS must
-// migrate to --artifacts-dir / --no-artifacts / --artifacts-exclude. We
-// print a clear pointer so failures don't bubble up as opaque "unknown
-// option" errors from Commander.
+// Hard-error on retired flags, env vars, and commands with a migration hint.
 // ---------------------------------------------------------------------------
-const RETIRED_FLAGS = [
-    "--capture",
-    "--capture-dir",
-    "--no-capture-compress",
-    "--no-capture-extras",
-    "--capture-exclude",
-];
+// Each entry maps an old identifier to the message shown when it's seen, so
+// failures don't bubble up as opaque "unknown option" errors from Commander.
+// W0052 retired the legacy artifact collector; W0075 retired the --skip-*
+// negation prefix, the --debug-{n,pattern,sample} filter flags, and several
+// top-level report/validator commands that were consolidated into umbrellas.
+// ---------------------------------------------------------------------------
+const RETIRED_CAPTURE_HINT = "   Use --artifacts-dir / --no-artifacts / --artifacts-exclude instead.\n" +
+    "   See docs/guides/cli-guide.md and docs/decisions/D0033-unified-run-anchored-artifact-capture.md.";
+const RETIRED_FLAG_HINTS = {
+    "--capture": RETIRED_CAPTURE_HINT,
+    "--capture-dir": RETIRED_CAPTURE_HINT,
+    "--no-capture-compress": RETIRED_CAPTURE_HINT,
+    "--no-capture-extras": RETIRED_CAPTURE_HINT,
+    "--capture-exclude": RETIRED_CAPTURE_HINT,
+    "--skip-fetch": "   Use --no-fetch instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--skip-eval": "   Use --no-eval instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--debug-n": "   Use --filter-first-n instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--debug-pattern": "   Use --filter-pattern instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--debug-sample": "   Use --filter-sample instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--output-format": "   Use --format instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--artifacts-dry-run": "   Use --no-artifacts-write instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "--readiness": "   Use `ailf report readiness --from-run <path>` instead. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "--discovery-report": "   Use `ailf report discovery --from-run <path>` instead. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "--compare-baseline": "   Use `--compare <path>` instead. `--compare` now takes an optional baseline argument. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "--before": "   Use --before-source instead. The flag was renamed to disambiguate from baseline comparison. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "--concurrency": "   Set `execution.concurrency` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6b).",
+    "--grader-replications": "   Set `execution.graderReplications` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6b).",
+    "--no-gap-analysis": "   Set `execution.gapAnalysis: false` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6b).",
+    "--api-url": "   Set `execution.apiUrl` in .ailf/config.yaml or use the AILF_API_URL env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6b).",
+    "--report-dataset": "   Set `reportStore.dataset` in .ailf/config.yaml or use the AILF_REPORT_DATASET env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6e).",
+    "--report-project": "   Set `reportStore.projectId` in .ailf/config.yaml or use the AILF_REPORT_PROJECT_ID env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6e).",
+    "--owner-team": "   Set `owner.team` in .ailf/config.yaml or use the AILF_OWNER_TEAM env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6f).",
+    "--owner-individual": "   Set `owner.individual` in .ailf/config.yaml or use the AILF_OWNER_INDIVIDUAL env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6f).",
+    "--header": "   Set `agentic.headers` (key/value object) in .ailf/config.yaml or use the DOC_HEADERS env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6f).",
+    "--allowed-origin": "   Set `agentic.allowedOrigins` (list of globs) in .ailf/config.yaml or use the DOC_ALLOWED_ORIGINS env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6f).",
+    "--task-source": "   Set `taskSource.type` (content-lake | repo) in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6h).",
+    "--repo-tasks-path": "   Set `taskSource.repoTasksPath` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6h).",
+};
+const RETIRED_COMMAND_HINTS = {
+    pipeline: "   Use `ailf run` instead. See docs/design-docs/pipeline-command-surface.md (W0077).",
+    "validate-tasks": "   Use `ailf validate tasks` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "readiness-report": "   Use `ailf report readiness` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "chronic-failures": "   Use `ailf report chronic-failures` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "coverage-audit": "   Use `ailf report coverage` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "discovery-report": "   Use `ailf report discovery` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "agent-report": "   Use `ailf report agent` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "weekly-digest": "   Use `ailf report digest` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+    "check-staleness": "   Use `ailf report staleness` instead. See docs/design-docs/cli-naming-convention.md (W0075).",
+};
+/**
+ * Per-subcommand retired-flag hints. Use this for flags that were retired
+ * from one subcommand but still exist on others (e.g. `--output-dir` is
+ * retired from `ailf run` but still present on `ailf publish`,
+ * `ailf pr-comment`, etc.). Keys are subcommand names; values share the
+ * same shape as `RETIRED_FLAG_HINTS`.
+ */
+const RETIRED_FLAG_HINTS_BY_COMMAND = {
+    run: {
+        "--output-dir": "   Set `output.dir` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6c).",
+        "--sanity-dataset": "   Set `source.dataset` in .ailf/config.yaml or use the SANITY_DATASET env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6d).",
+        "--sanity-project": "   Set `source.projectId` in .ailf/config.yaml or use the SANITY_PROJECT_ID env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6d).",
+        "--sanity-studio-origin": "   Set `source.studioOrigin` in .ailf/config.yaml or use the SANITY_STUDIO_ORIGIN env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6d).",
+        "--no-artifacts": "   Set `artifacts.enabled: false` in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6g).",
+        "--artifacts-dir": "   Set `artifacts.dir` in .ailf/config.yaml or use the AILF_ARTIFACTS_DIR env var. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6g).",
+        "--artifacts-exclude": "   Set `artifacts.exclude` (list of artifact-type names) in .ailf/config.yaml instead. See docs/design-docs/pipeline-command-surface.md (W0077 Phase 6g).",
+    },
+};
 const RETIRED_ENV_VARS = [
     "AILF_CAPTURE",
     "AILF_CAPTURE_DIR",
@@ -102,15 +155,45 @@ const RETIRED_ENV_VARS = [
     "AILF_LEGACY_COLLECTOR",
     "AILF_UNIFIED_ARTIFACTS",
 ];
+/**
+ * Identify the subcommand the user invoked — the first non-flag arg after
+ * `ailf` (argv[0]=node, argv[1]=cli.ts). Returns undefined if none.
+ */
+function findInvokedSubcommand() {
+    for (let i = 2; i < process.argv.length; i++) {
+        const arg = process.argv[i];
+        if (!arg.startsWith("-"))
+            return arg;
+    }
+    return undefined;
+}
 function findRetiredFlag() {
+    const subcommand = findInvokedSubcommand();
+    const subcommandHints = subcommand
+        ? RETIRED_FLAG_HINTS_BY_COMMAND[subcommand]
+        : undefined;
     for (const arg of process.argv) {
         const bare = arg.split("=")[0];
-        if (RETIRED_FLAGS.includes(bare)) {
-            return bare;
+        if (subcommandHints && bare in subcommandHints) {
+            return { flag: bare, hint: subcommandHints[bare] };
+        }
+        if (bare in RETIRED_FLAG_HINTS) {
+            return { flag: bare, hint: RETIRED_FLAG_HINTS[bare] };
         }
     }
     return undefined;
 }
+function findRetiredCommand() {
+    // The first non-flag argument after `ailf` (argv[0]=node, argv[1]=cli.ts).
+    for (let i = 2; i < process.argv.length; i++) {
+        const arg = process.argv[i];
+        if (!arg.startsWith("-") && arg in RETIRED_COMMAND_HINTS)
+            return arg;
+        if (!arg.startsWith("-"))
+            return undefined;
+    }
+    return undefined;
+}
 function findRetiredEnv() {
     for (const name of RETIRED_ENV_VARS) {
         if (process.env[name] !== undefined)
@@ -119,14 +202,21 @@ function findRetiredEnv() {
     return undefined;
 }
 const retiredFlag = findRetiredFlag();
+const retiredCommand = findRetiredCommand();
 const retiredEnv = findRetiredEnv();
-if (retiredFlag || retiredEnv) {
-    const source = retiredFlag
-        ? `flag "${retiredFlag}"`
-        : `environment variable "${retiredEnv}"`;
-    console.error(`❌ ${source} was retired in W0052 along with the legacy artifact collector.`);
-    console.error("   Use --artifacts-dir / --no-artifacts / --artifacts-exclude instead.");
-    console.error("   See docs/cli.md and docs/decisions/D0033-unified-run-anchored-artifact-capture.md.");
+if (retiredFlag || retiredCommand || retiredEnv) {
+    if (retiredFlag) {
+        console.error(`❌ flag "${retiredFlag.flag}" was retired.`);
+        console.error(retiredFlag.hint);
+    }
+    else if (retiredCommand) {
+        console.error(`❌ command "${retiredCommand}" was retired.`);
+        console.error(RETIRED_COMMAND_HINTS[retiredCommand]);
+    }
+    else if (retiredEnv) {
+        console.error(`❌ environment variable "${retiredEnv}" was retired in W0052 along with the legacy artifact collector.`);
+        console.error(RETIRED_CAPTURE_HINT);
+    }
     process.exit(2);
 }
 // ---------------------------------------------------------------------------
@@ -180,8 +270,8 @@ program.hook("preAction", async (thisCommand, actionCommand) => {
 // Within each group, commands appear in the order they are added.
 // ---------------------------------------------------------------------------
 // ── Core Workflow ──────────────────────────────────────────────────────
-import { createPipelineCommand } from "./commands/pipeline.js";
-program.addCommand(createPipelineCommand().helpGroup(CommandGroup.CoreWorkflow));
+import { createRunCommand } from "./commands/run.js";
+program.addCommand(createRunCommand().helpGroup(CommandGroup.CoreWorkflow));
 import { createCompareCommand } from "./commands/compare.js";
 program.addCommand(createCompareCommand().helpGroup(CommandGroup.CoreWorkflow));
 import { createBaselineCommand } from "./commands/baseline.js";
@@ -192,29 +282,35 @@ import { createRunsCommand } from "./commands/runs.js";
 program.addCommand(createRunsCommand().helpGroup(CommandGroup.CoreWorkflow));
 // ── Analysis & Reports ────────────────────────────────────────────────
 import { createReadinessReportCommand } from "./commands/readiness-report.js";
-program.addCommand(createReadinessReportCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createChronicFailuresCommand } from "./commands/chronic-failures.js";
-program.addCommand(createChronicFailuresCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createCoverageAuditCommand } from "./commands/coverage-audit.js";
-program.addCommand(createCoverageAuditCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createDiscoveryReportCommand } from "./commands/discovery-report.js";
-program.addCommand(createDiscoveryReportCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createAgentReportCommand } from "./commands/agent-report.js";
-program.addCommand(createAgentReportCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createWeeklyDigestCommand } from "./commands/weekly-digest.js";
-program.addCommand(createWeeklyDigestCommand().helpGroup(CommandGroup.AnalysisReports));
 import { createCheckStalenessCommand } from "./commands/check-staleness.js";
-program.addCommand(createCheckStalenessCommand().helpGroup(CommandGroup.AnalysisReports));
+const reportCommand = new Command("report")
+    .description("Generate analysis and reporting outputs from evaluation runs")
+    .addCommand(createReadinessReportCommand())
+    .addCommand(createChronicFailuresCommand())
+    .addCommand(createCoverageAuditCommand())
+    .addCommand(createDiscoveryReportCommand())
+    .addCommand(createAgentReportCommand())
+    .addCommand(createWeeklyDigestCommand())
+    .addCommand(createCheckStalenessCommand());
+program.addCommand(reportCommand.helpGroup(CommandGroup.AnalysisReports));
 // ── Grader Reliability ────────────────────────────────────────────────
 import { createGraderCommand } from "./commands/grader/index.js";
 program.addCommand(createGraderCommand().helpGroup(CommandGroup.GraderReliability));
 // ── Setup & Configuration ─────────────────────────────────────────────
 import { createInitCommand } from "./commands/init.js";
 program.addCommand(createInitCommand().helpGroup(CommandGroup.SetupConfig));
-import { createValidateCommand } from "./commands/validate.js";
-program.addCommand(createValidateCommand().helpGroup(CommandGroup.SetupConfig));
+import { createValidateConfigCommand } from "./commands/validate.js";
 import { createValidateTasksCommand } from "./commands/validate-tasks.js";
-program.addCommand(createValidateTasksCommand().helpGroup(CommandGroup.SetupConfig));
+const validateCommand = new Command("validate")
+    .description("Validate AILF configuration and task files")
+    .addCommand(createValidateConfigCommand())
+    .addCommand(createValidateTasksCommand());
+program.addCommand(validateCommand.helpGroup(CommandGroup.SetupConfig));
 import { createFetchDocsCommand } from "./commands/fetch-docs.js";
 program.addCommand(createFetchDocsCommand().helpGroup(CommandGroup.SetupConfig));
 import { createCacheCommand } from "./commands/cache.js";

package/dist/commands/agent-report.js

@@ -6,7 +6,7 @@ import { dirname, join } from "path";
 import { Command } from "commander";
 import { analyzeResults } from "../pipeline/agent-behavior-report.js";
 export function createAgentReportCommand() {
-    return new Command("agent-report")
+    return new Command("agent")
         .description("Generate an agent behavior observation report from eval results")
         .argument("[results-path]", "Path to eval-results.json (default: results/latest/eval-results.json)")
         .action(async (resultsPath) => {

package/dist/commands/calculate-scores.js

@@ -30,8 +30,6 @@ export function createCalculateScoresCommand() {
                 skipEval: true,
                 compareEnabled: false,
                 gapAnalysisEnabled: false,
-                readinessEnabled: false,
-                discoveryReportEnabled: false,
                 publishEnabled: false,
                 noCache: true,
                 noRemoteCache: true,

package/dist/commands/check-staleness.js

@@ -12,7 +12,7 @@
  */
 import { Command } from "commander";
 export function createCheckStalenessCommand() {
-    return new Command("check-staleness")
+    return new Command("staleness")
         .description("Exit 1 if no evaluation report has been produced within the max-age window")
         .option("--max-age <days>", "Max age in days before reports are considered stale", (v) => Number.parseInt(v, 10), 3)
         .action(async (opts) => {

package/dist/commands/chronic-failures.js

@@ -11,15 +11,15 @@ export function createChronicFailuresCommand() {
     return new Command("chronic-failures")
         .description("Identify tasks that error in >50% of recent evaluation runs")
         .option("--lookback <n>", "Number of recent reports to analyze", (v) => parseInt(v, 10), 10)
-        .option("--threshold <n>", "Error rate threshold (0-1) for chronic classification", (v) => parseFloat(v), 0.5)
-        .option("--json", "Output raw JSON", false)
+        .option("--error-rate <n>", "Error rate threshold (0-1) for chronic classification", (v) => parseFloat(v), 0.5)
+        .option("-f, --format <fmt>", "Output format: console or json", "console")
         .action(async (opts) => {
         const reportStore = new ReportStore();
         const report = await detectChronicFailures(reportStore, {
             lookback: opts.lookback,
-            threshold: opts.threshold,
+            threshold: opts.errorRate,
         });
-        if (opts.json) {
+        if (opts.format === "json") {
             console.log(JSON.stringify(report, null, 2));
         }
         else {

package/dist/commands/coverage-audit.js

@@ -13,10 +13,9 @@ import { createSanityLiteracyPreset } from "../pipeline/compiler/presets/index.j
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, "..", "..");
 export function createCoverageAuditCommand() {
-    return new Command("coverage-audit")
+    return new Command("coverage")
         .description("Run documentation coverage audit against feature registry")
-        .option("--format <fmt>", "Output format: table, md, markdown")
-        .option("--json", "Output raw JSON", false)
+        .option("-f, --format <fmt>", "Output format: table, md, markdown, json", "table")
         .action(async (opts) => {
         // Build a registry with mode base + preset so coverage audit works
         // even when config/features.ts is empty (preset is source of truth).
@@ -28,17 +27,17 @@ export function createCoverageAuditCommand() {
             console.error("❌ Coverage audit failed. Ensure config/features.yaml exists and is valid.");
             process.exit(1);
         }
-        if (opts.json) {
+        const isMarkdown = opts.format === "md" || opts.format === "markdown";
+        if (opts.format === "json") {
             console.log(JSON.stringify(report, null, 2));
         }
-        else if (opts.format === "md" || opts.format === "markdown") {
+        else if (isMarkdown) {
             console.log(formatCoverageMarkdown(report));
         }
         else {
             console.log(formatCoverageConsole(report));
         }
-        // Print document utilization stats for non-JSON console output
-        if (!opts.json && opts.format !== "md" && opts.format !== "markdown") {
+        if (opts.format !== "json" && !isMarkdown) {
             const docStats = countReferencedDocs(ROOT);
             console.log("DOCUMENT UTILIZATION:");
             console.log(`  ${docStats.total} unique document slugs referenced across evaluation tasks`);

package/dist/commands/discovery-report.js

@@ -13,17 +13,29 @@ import { fileURLToPath } from "url";
 import { formatDiscoveryMarkdown, generateDiscoveryReport, } from "../pipeline/discovery-report.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, "..", "..");
+const DEFAULT_RESULTS_DIR = join(ROOT, "results", "latest");
+/** Resolve `--from-run` to an absolute path to score-summary.json. */
+function resolveFromRun(value) {
+    if (value === "latest")
+        return join(DEFAULT_RESULTS_DIR, "score-summary.json");
+    // If the value points at a directory, look for score-summary.json inside it.
+    // Otherwise treat it as a direct file path.
+    const resolved = resolve(value);
+    return resolved.endsWith(".json")
+        ? resolved
+        : join(resolved, "score-summary.json");
+}
 export function createDiscoveryReportCommand() {
-    return new Command("discovery-report")
+    return new Command("discovery")
         .description("Generate agent discoverability report from retrieval metrics")
         .option("-a, --area <areas>", "Filter by feature areas (comma-separated)")
         .option("-o, --output <path>", "Write markdown to file instead of stdout")
-        .option("-i, --input <path>", "Path to score-summary.json", join(ROOT, "results", "latest", "score-summary.json"))
+        .option("--from-run <path>", "Results to read from (`latest`, a results directory, or a direct path to score-summary.json)", "latest")
         .action(async (opts) => {
-        const summaryPath = opts.input;
+        const summaryPath = resolveFromRun(opts.fromRun);
         if (!existsSync(summaryPath)) {
             console.error(`❌ Score summary not found: ${summaryPath}`);
-            console.error("Run an agentic evaluation first: pnpm pipeline -- --mode agentic");
+            console.error("Run an agentic evaluation first: ailf run --mode agentic");
             process.exit(1);
         }
         const summary = JSON.parse(readFileSync(summaryPath, "utf-8"));

package/dist/commands/eval.d.ts

@@ -2,7 +2,7 @@
  * eval command — run promptfoo evaluation directly (passthrough).
  *
  * This is a convenience command that forwards to `promptfoo eval`.
- * For most use cases, prefer `ailf pipeline` which handles the full
+ * For most use cases, prefer `ailf run` which handles the full
  * lifecycle (fetch → generate → eval → score → report).
  */
 import { Command } from "commander";

package/dist/commands/eval.js

@@ -2,7 +2,7 @@
  * eval command — run promptfoo evaluation directly (passthrough).
  *
  * This is a convenience command that forwards to `promptfoo eval`.
- * For most use cases, prefer `ailf pipeline` which handles the full
+ * For most use cases, prefer `ailf run` which handles the full
  * lifecycle (fetch → generate → eval → score → report).
  */
 import { Command } from "commander";

package/dist/commands/explain-handler.d.ts

@@ -12,7 +12,7 @@
  * Every command is registered in `EXPLAIN_REGISTRY` with either:
  * - **Static metadata** — description, filesRead, filesCreated, steps
  * - **A builder function** — for commands that need to inspect CLI options
- *   or perform async work (e.g., pipeline, init)
+ *   or perform async work (e.g., run, init)
  *
  * Adding --explain support for a new command = adding one registry entry.
  * Commands not in the registry fall back to a minimal generic plan.

package/dist/commands/explain-handler.js

@@ -12,7 +12,7 @@
  * Every command is registered in `EXPLAIN_REGISTRY` with either:
  * - **Static metadata** — description, filesRead, filesCreated, steps
  * - **A builder function** — for commands that need to inspect CLI options
- *   or perform async work (e.g., pipeline, init)
+ *   or perform async work (e.g., run, init)
  *
  * Adding --explain support for a new command = adding one registry entry.
  * Commands not in the registry fall back to a minimal generic plan.
@@ -39,7 +39,7 @@ const EXPLAIN_REGISTRY = {
     // ── Dynamic builders (inspect CLI options) ────────────────────────
     baseline: buildBaselineExplainPlan,
     init: buildInitExplainPlan,
-    pipeline: buildPipelineExplainPlan,
+    run: buildPipelineExplainPlan,
     // ── Static metadata ───────────────────────────────────────────────
     "agent-report": {
         description: "Generate an agent behavior observation report from eval results",
@@ -588,15 +588,11 @@ export async function handleExplain(actionCommand, confirmExecution, rootDir) {
  * Build a plan for the `init` command.
  *
  * Shows which files and directories will be created, taking into
- * account the --output-format and --path flags.
+ * account the --format and --path flags.
  */
 function buildInitExplainPlan(actionCommand, rootDir) {
     const opts = actionCommand.opts();
-    const format = opts.outputFormat === "json"
-        ? "json"
-        : opts.outputFormat === "yaml"
-            ? "yaml"
-            : "ts";
+    const format = opts.format === "json" ? "json" : opts.format === "yaml" ? "yaml" : "ts";
     const taskExt = format === "ts" ? ".task.ts" : format === "yaml" ? ".yaml" : ".json";
     const configFile = format === "ts"
         ? "ailf.config.ts"
@@ -667,69 +663,44 @@ function buildBaselineExplainPlan(actionCommand, rootDir) {
     });
 }
 /**
- * Build a plan for the `pipeline` command — the richest plan with steps,
+ * Build a plan for the `run` command — the richest plan with steps,
  * tasks, models, cost estimates, and cache predictions.
  */
 async function buildPipelineExplainPlan(actionCommand, rootDir) {
     const raw = actionCommand.opts();
     // Merge Commander-parsed opts with safe defaults for array/boolean fields
     const withDefaults = {
-        allowedOrigin: raw.allowedOrigin ?? [],
-        allowedOrigins: raw.allowedOrigins ?? [],
         area: raw.area,
         autoScope: raw.autoScope ?? true,
-        before: raw.before,
+        beforeSource: raw.beforeSource,
         cache: raw.cache ?? true,
         changedDocs: raw.changedDocs,
-        compare: raw.compare ?? false,
-        compareBaseline: raw.compareBaseline,
-        concurrency: raw.concurrency,
+        compare: raw.compare,
         debug: raw.debug ?? false,
-        debugN: raw.debugN,
-        debugPattern: raw.debugPattern,
-        debugSample: raw.debugSample,
-        discoveryReport: raw.discoveryReport ?? false,
+        filterFirstN: raw.filterFirstN,
+        filterPattern: raw.filterPattern,
+        filterSample: raw.filterSample,
         dryRun: raw.dryRun ?? false,
-        gapAnalysis: raw.gapAnalysis ?? true,
-        graderReplications: raw.graderReplications,
-        header: raw.header ?? [],
-        headers: raw.headers ?? [],
         mode: raw.mode ?? LiteracyVariant.FULL,
         output: raw.output,
         promptfooUrl: raw.promptfooUrl,
         publish: raw.publish,
         publishTag: raw.publishTag,
-        readiness: raw.readiness ?? false,
-        reportDataset: raw.reportDataset,
-        reportProject: raw.reportProject,
-        sanityDataset: raw.sanityDataset,
         sanityDocument: raw.sanityDocument ?? [],
-        sanityDocuments: raw.sanityDocuments ?? [],
         sanityPerspective: raw.sanityPerspective,
-        sanityProject: raw.sanityProject,
-        sanityStudioOrigin: raw.sanityStudioOrigin,
         search: raw.search,
-        skipEval: raw.skipEval ?? false,
-        skipFetch: raw.skipFetch ?? false,
+        eval: raw.eval ?? true,
+        fetch: raw.fetch ?? true,
         source: raw.source,
         tag: raw.tag ?? [],
         task: raw.task,
         threshold: raw.threshold,
         url: raw.url ?? [],
-        urls: raw.urls ?? [],
         remote: raw.remote ?? false,
-        apiUrl: raw.apiUrl,
-        repoTasksPath: raw.repoTasksPath,
-        taskSource: raw.taskSource,
         remoteCache: raw.remoteCache,
         config: raw.config,
-        artifacts: raw.artifacts ?? true,
-        artifactsDir: raw.artifactsDir,
-        artifactsDryRun: raw.artifactsDryRun ?? false,
-        artifactsExclude: raw.artifactsExclude,
+        artifactsWrite: raw.artifactsWrite ?? true,
         classification: raw.classification,
-        ownerTeam: raw.ownerTeam,
-        ownerIndividual: raw.ownerIndividual,
         purpose: raw.purpose,
         label: raw.label ?? [],
     };
@@ -742,7 +713,6 @@ async function buildPipelineExplainPlan(actionCommand, rootDir) {
         compareThreshold: resolved.compareThreshold,
         concurrency: resolved.concurrency,
         debug: resolved.debug,
-        discoveryReportEnabled: resolved.discoveryReportEnabled,
         dryRun: resolved.dryRun,
         gapAnalysisEnabled: resolved.gapAnalysisEnabled,
         graderReplications: resolved.graderReplications,
@@ -750,7 +720,6 @@ async function buildPipelineExplainPlan(actionCommand, rootDir) {
         variant: resolved.variant,
         noCache: resolved.noCache,
         publishEnabled: resolved.publishEnabled,
-        readinessEnabled: resolved.readinessEnabled,
         skipEval: resolved.skipEval,
         skipFetch: resolved.skipFetch,
         source: resolved.source,

package/dist/commands/fetch-docs.js

@@ -50,8 +50,6 @@ async function executeFetchDocs(opts) {
         skipEval: true,
         compareEnabled: false,
         gapAnalysisEnabled: false,
-        readinessEnabled: false,
-        discoveryReportEnabled: false,
         publishEnabled: false,
         noCache: true,
         noRemoteCache: true,

package/dist/commands/generate-configs.js

@@ -28,8 +28,6 @@ export function createGenerateConfigsCommand() {
                 skipEval: true,
                 compareEnabled: false,
                 gapAnalysisEnabled: false,
-                readinessEnabled: false,
-                discoveryReportEnabled: false,
                 publishEnabled: false,
                 noCache: true,
                 noRemoteCache: true,

package/dist/commands/grader/index.js

@@ -95,16 +95,16 @@ export function createGraderCommand() {
         .command("validate")
         .description("Validate grader accuracy against human reference grades")
         .option("-g, --grader <model>", "Grader model to validate")
-        .option("-t, --threshold <n>", "MAE threshold for pass/fail", parseFloat, 10)
+        .option("--mae-threshold <n>", "MAE threshold for pass/fail", parseFloat, 10)
         .action(async (opts) => {
         try {
             const result = await runGraderValidate({
                 graderModel: opts.grader,
-                maeThreshold: opts.threshold,
+                maeThreshold: opts.maeThreshold,
                 rootDir: ROOT,
             });
             if (!result.passesThreshold) {
-                console.error(`\n  ❌ VALIDATION FAILED: MAE ${result.overallMae} exceeds threshold ${opts.threshold}`);
+                console.error(`\n  ❌ VALIDATION FAILED: MAE ${result.overallMae} exceeds threshold ${opts.maeThreshold}`);
                 process.exit(1);
             }
         }

package/dist/commands/init.d.ts

@@ -11,8 +11,8 @@
  *
  * Usage:
  *   ailf init                        # TypeScript output (default)
- *   ailf init --output-format yaml   # YAML output
- *   ailf init --output-format json   # JSON output
+ *   ailf init --format yaml          # YAML output
+ *   ailf init --format json          # JSON output
  *   ailf init --force                # overwrite existing files
  *   ailf init --path ./my-dir        # target a specific directory
  */

package/dist/commands/init.js

@@ -11,8 +11,8 @@
  *
  * Usage:
  *   ailf init                        # TypeScript output (default)
- *   ailf init --output-format yaml   # YAML output
- *   ailf init --output-format json   # JSON output
+ *   ailf init --format yaml          # YAML output
+ *   ailf init --format json          # JSON output
  *   ailf init --force                # overwrite existing files
  *   ailf init --path ./my-dir        # target a specific directory
  */
@@ -27,7 +27,7 @@ import { probeUserLocalAilf } from "../adapters/config-sources/ailf-resolver.js"
 export function createInitCommand() {
     return new Command("init")
         .description("Initialize a directory for AI Literacy Framework evaluation")
-        .option("--output-format <fmt>", 'Output format for generated files: "ts" (default), "yaml", or "json"', "ts")
+        .option("-f, --format <fmt>", 'Output format for generated files: "ts" (default), "yaml", or "json"', "ts")
         .option("--force", "Overwrite existing files", false)
         .option("--path <dir>", "Target directory (default: current directory)", ".")
         .option("--mode <mode>", "Scaffold for a specific mode: literacy, mcp-server, custom (default: all modes)")
@@ -63,15 +63,15 @@ function taskStemsForMode(mode) {
 // ---------------------------------------------------------------------------
 async function runInit(opts) {
     const validFormats = new Set(["ts", "yaml", "json"]);
-    if (!validFormats.has(opts.outputFormat)) {
-        console.error(`  ✗ Invalid output format "${opts.outputFormat}". Valid options: ts, yaml, json`);
+    if (!validFormats.has(opts.format)) {
+        console.error(`  ✗ Invalid output format "${opts.format}". Valid options: ts, yaml, json`);
         process.exitCode = 1;
         return;
     }
-    const format = opts.outputFormat;
+    const format = opts.format;
     const force = opts.force;
     if (format === "yaml") {
-        console.warn("  ⚠ --output-format yaml is deprecated. TypeScript (default) is the\n" +
+        console.warn("  ⚠ --format yaml is deprecated. TypeScript (default) is the\n" +
             "    recommended format — it provides full IDE autocomplete via defineTask().\n" +
             "    YAML output will be removed in a future release.\n");
     }
@@ -285,10 +285,11 @@ async function runInit(opts) {
     console.log("     AILF_API_KEY=... npx @sanity/ailf@latest pipeline --remote --debug");
     console.log();
     console.log("  💡 Or test a remote run against your repo tasks:");
-    console.log("     AILF_API_KEY=... npx @sanity/ailf@latest pipeline --remote --task-source=repo --debug");
+    console.log("     # First, set `taskSource: { type: repo }` in .ailf/config.yaml");
+    console.log("     AILF_API_KEY=... npx @sanity/ailf@latest run --remote --debug");
     console.log();
     console.log("  💡 Or run locally against your repo tasks:");
-    console.log("     AILF_API_KEY=... npx @sanity/ailf@latest pipeline --mode=literacy --variant=full --task-source=repo --debug --explain -y");
+    console.log("     AILF_API_KEY=... npx @sanity/ailf@latest run --mode=literacy --variant=full --debug --explain -y");
     console.log();
 }
 // ---------------------------------------------------------------------------