@sanity/ailf 3.7.0 → 3.8.1

package/dist/cli.js

@@ -1,6 +1,4 @@
 #!/usr/bin/env node
-/* oxlint-disable import/first -- imports are intentionally interleaved with
-   command registration for readability and lazy loading */
 /**
  * cli.ts — AILF CLI entry point.
  *
@@ -13,7 +11,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,16 +24,21 @@
  *   --dotenv <path>             # override default .env path
  *
  * Dev mode (without building):
- *   tsx src/cli.ts pipeline --debug
+ *   tsx src/cli.ts run --debug
+ *
+ * Module split: this file owns *bootstrap side effects* (dotenv,
+ * retired-flag/env/cmd checks, AILF_LOG_LEVEL pre-scan, parseAsync).
+ * The Commander wiring lives in ./cli-program.ts so the W0078 M4 black-box
+ * harness can build the program in-process without firing those side
+ * effects.
  */
 import { config as dotenvConfig } from "dotenv";
-import { existsSync, readFileSync } from "fs";
+import { existsSync } from "fs";
 import { dirname, resolve } from "path";
 import { fileURLToPath } from "url";
+import { buildCliProgram } from "./cli-program.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const ROOT = resolve(__dirname, "..");
-/** Path to the eval package root (packages/eval). Used by --explain. */
-const EVAL_ROOT = ROOT;
 // ---------------------------------------------------------------------------
 // Load .env — must happen before Commander parses so that .env()
 // fallbacks resolve correctly.
@@ -76,22 +79,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,12 +158,42 @@ 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;
 }
@@ -119,132 +205,32 @@ 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);
 }
 // ---------------------------------------------------------------------------
-// Build CLI program
+// Build CLI program (delegates Commander wiring to ./cli-program.ts)
 // ---------------------------------------------------------------------------
-import { Command } from "commander";
-import { CommandGroup, configureProgram } from "./commands/shared/help.js";
-// Read version from package.json
-const pkgPath = resolve(ROOT, "package.json");
-const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
-const program = new Command()
-    .name("ailf")
-    .description("AI Literacy Framework — evaluate how well docs enable AI coding tools\n\nMeasure whether AI coding agents can find the right documentation\nand produce correct implementations of your product features.")
-    .version(pkg.version)
-    .option("-v, --verbose", "Increase log output")
-    .option("-q, --quiet", "Suppress non-error output")
-    .option("--dotenv <path>", "Override default .env file path")
-    .option("--explain", "Show execution plan without running")
-    .option("--format <fmt>", "Output format for --explain (console, json)", "console")
-    .option("-y, --yes", "With --explain: show plan then prompt to confirm execution");
-configureProgram(program);
+const program = buildCliProgram({ evalRoot: ROOT });
 // ---------------------------------------------------------------------------
-// Global --explain hook — intercepts any command before execution
-// ---------------------------------------------------------------------------
-program.hook("preAction", async (thisCommand, actionCommand) => {
-    const globalOpts = thisCommand.opts();
-    if (!globalOpts.explain)
-        return;
-    const { handleExplain } = await import("./commands/explain-handler.js");
-    try {
-        await handleExplain(actionCommand, globalOpts.yes ?? false, EVAL_ROOT);
-        process.exit(0);
-    }
-    catch (err) {
-        // Sentinel from --yes confirmation: user wants to proceed
-        if (err !== null &&
-            typeof err === "object" &&
-            "__proceedArgv" in err) {
-            const filteredArgv = err.__proceedArgv;
-            console.log("\n  ▸ Proceeding with execution…\n");
-            await program.parseAsync(filteredArgv);
-            return;
-        }
-        throw err;
-    }
-});
-// ---------------------------------------------------------------------------
-// Register commands
+// Parse and run — default to showing help when no arguments given.
 //
-// Registration order determines group display order in --help.
-// 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 { createCompareCommand } from "./commands/compare.js";
-program.addCommand(createCompareCommand().helpGroup(CommandGroup.CoreWorkflow));
-import { createBaselineCommand } from "./commands/baseline.js";
-program.addCommand(createBaselineCommand().helpGroup(CommandGroup.CoreWorkflow));
-import { createPublishCommand } from "./commands/publish.js";
-program.addCommand(createPublishCommand().helpGroup(CommandGroup.CoreWorkflow));
-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));
-// ── 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 { createValidateTasksCommand } from "./commands/validate-tasks.js";
-program.addCommand(createValidateTasksCommand().helpGroup(CommandGroup.SetupConfig));
-import { createFetchDocsCommand } from "./commands/fetch-docs.js";
-program.addCommand(createFetchDocsCommand().helpGroup(CommandGroup.SetupConfig));
-import { createCacheCommand } from "./commands/cache.js";
-program.addCommand(createCacheCommand().helpGroup(CommandGroup.SetupConfig));
-// ── Pipeline Internals ────────────────────────────────────────────────
-import { createEvalCommand } from "./commands/eval.js";
-program.addCommand(createEvalCommand().helpGroup(CommandGroup.PipelineInternals));
-import { createCalculateScoresCommand } from "./commands/calculate-scores.js";
-program.addCommand(createCalculateScoresCommand().helpGroup(CommandGroup.PipelineInternals));
-import { createPrCommentCommand } from "./commands/pr-comment.js";
-program.addCommand(createPrCommentCommand().helpGroup(CommandGroup.PipelineInternals));
-import { createGenerateConfigsCommand } from "./commands/generate-configs.js";
-program.addCommand(createGenerateConfigsCommand().helpGroup(CommandGroup.PipelineInternals));
-import { createMeasureRetrievalCommand } from "./commands/measure-retrieval.js";
-program.addCommand(createMeasureRetrievalCommand().helpGroup(CommandGroup.PipelineInternals));
-import { createLookupDocCommand } from "./commands/lookup-doc.js";
-program.addCommand(createLookupDocCommand().helpGroup(CommandGroup.PipelineInternals));
-import { createWebhookServerCommand } from "./commands/webhook-server.js";
-program.addCommand(createWebhookServerCommand().helpGroup(CommandGroup.PipelineInternals));
-// ── Developer Tools ───────────────────────────────────────────────────
-import { createInteractiveCommand } from "./commands/interactive.js";
-program.addCommand(createInteractiveCommand().helpGroup(CommandGroup.DeveloperTools));
-// Shell completion — must be registered last (needs full program tree)
-import { createCompletionCommand } from "./commands/completion.js";
-program.addCommand(createCompletionCommand(program).helpGroup(CommandGroup.DeveloperTools));
-// ---------------------------------------------------------------------------
-// Parse and run — default to showing help when no arguments given
-// ---------------------------------------------------------------------------
-// If no command is specified (just `ailf`), show help.
 // The interactive wizard is still available via `ailf interactive`.
+// ---------------------------------------------------------------------------
 if (process.argv.length <= 2) {
     program.outputHelp();
 }

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,