@kirrosh/zond 0.18.0 → 0.20.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kirrosh/zond",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "API testing platform — define tests in YAML, run from CLI or WebUI, generate from OpenAPI specs",
   "license": "MIT",
   "module": "index.ts",
@@ -37,6 +37,9 @@
   "devDependencies": {
     "@types/bun": "latest"
   },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
   "peerDependencies": {
     "typescript": "^5"
   },

package/src/cli/commands/coverage.ts

@@ -50,6 +50,10 @@ export async function coverageCommand(options: CoverageOptions): Promise<number>
     const color = useColor();
 
     // Enriched mode with run results
+    let passing = 0;
+    let apiError = 0;
+    let testFailed = 0;
+
     if (options.runId != null) {
       getDb();
       const run = getRunById(options.runId);
@@ -88,62 +92,63 @@ export async function coverageCommand(options: CoverageOptions): Promise<number>
         }
       }
 
-      let passing = 0;
-      let apiError = 0;
-      let testFailed = 0;
       for (const status of endpointStatus.values()) {
         if (status === "passing") passing++;
         else if (status === "api_error") apiError++;
         else if (status === "test_failed") testFailed++;
       }
+    }
 
-      console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%) — Run #${options.runId}`);
-      console.log("");
+    if (!options.json) {
+      if (options.runId != null) {
+        console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%) — Run #${options.runId}`);
+        console.log("");
 
-      if (passing > 0) {
-        console.log(`  ${color ? GREEN : ""}✅ ${passing} covered and passing${color ? RESET : ""}`);
-      }
-      if (apiError > 0) {
-        console.log(`  ${color ? YELLOW : ""}⚠️  ${apiError} covered but returning 5xx (possibly broken API)${color ? RESET : ""}`);
-      }
-      if (testFailed > 0) {
-        console.log(`  ${color ? RED : ""}❌ ${testFailed} covered, test assertions failed${color ? RESET : ""}`);
-      }
-      if (uncovered.length > 0) {
-        console.log(`  ${color ? DIM : ""}⬜ ${uncovered.length} not covered${color ? RESET : ""}`);
-      }
-    } else {
-      // Standard mode
-      console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%)`);
-      console.log("");
+        if (passing > 0) {
+          console.log(`  ${color ? GREEN : ""}✅ ${passing} covered and passing${color ? RESET : ""}`);
+        }
+        if (apiError > 0) {
+          console.log(`  ${color ? YELLOW : ""}⚠️  ${apiError} covered but returning 5xx (possibly broken API)${color ? RESET : ""}`);
+        }
+        if (testFailed > 0) {
+          console.log(`  ${color ? RED : ""}❌ ${testFailed} covered, test assertions failed${color ? RESET : ""}`);
+        }
+        if (uncovered.length > 0) {
+          console.log(`  ${color ? DIM : ""}⬜ ${uncovered.length} not covered${color ? RESET : ""}`);
+        }
+      } else {
+        // Standard mode
+        console.log(`Coverage: ${coveredCount}/${allEndpoints.length} endpoints (${percentage}%)`);
+        console.log("");
 
-      // Covered endpoints
-      if (coveredCount > 0) {
-        console.log(`${color ? GREEN : ""}Covered:${color ? RESET : ""}`);
-        for (const ep of allEndpoints) {
-          if (!uncovered.includes(ep)) {
-            console.log(`  ${color ? GREEN : ""}✓${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+        // Covered endpoints
+        if (coveredCount > 0) {
+          console.log(`${color ? GREEN : ""}Covered:${color ? RESET : ""}`);
+          for (const ep of allEndpoints) {
+            if (!uncovered.includes(ep)) {
+              console.log(`  ${color ? GREEN : ""}✓${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+            }
           }
+          console.log("");
         }
-        console.log("");
-      }
 
-      // Uncovered endpoints
-      if (uncovered.length > 0) {
-        console.log(`${color ? RED : ""}Uncovered:${color ? RESET : ""}`);
-        for (const ep of uncovered) {
-          console.log(`  ${color ? RED : ""}✗${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+        // Uncovered endpoints
+        if (uncovered.length > 0) {
+          console.log(`${color ? RED : ""}Uncovered:${color ? RESET : ""}`);
+          for (const ep of uncovered) {
+            console.log(`  ${color ? RED : ""}✗${color ? RESET : ""} ${ep.method.padEnd(7)} ${ep.path}`);
+          }
         }
       }
-    }
 
-    // Static warnings (always shown)
-    const warnings = analyzeEndpoints(allEndpoints);
-    if (warnings.length > 0) {
-      console.log("");
-      console.log(`${color ? YELLOW : ""}Spec warnings:${color ? RESET : ""}`);
-      for (const w of warnings) {
-        console.log(`  ${color ? YELLOW : ""}⚠${color ? RESET : ""} ${w.method.padEnd(7)} ${w.path}: ${w.warnings.join(", ")}`);
+      // Static warnings (always shown in human-readable mode)
+      const warnings = analyzeEndpoints(allEndpoints);
+      if (warnings.length > 0) {
+        console.log("");
+        console.log(`${color ? YELLOW : ""}Spec warnings:${color ? RESET : ""}`);
+        for (const w of warnings) {
+          console.log(`  ${color ? YELLOW : ""}⚠${color ? RESET : ""} ${w.method.padEnd(7)} ${w.path}: ${w.warnings.join(", ")}`);
+        }
       }
     }
 

package/src/cli/commands/db.ts

@@ -1,4 +1,6 @@
 import { getCollections, getRuns, getRunDetail, diagnoseRun, compareRuns } from "../../core/diagnostics/db-analysis.ts";
+import { getFilteredResults } from "../../db/queries.ts";
+import { getDb } from "../../db/schema.ts";
 import { printError } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 
@@ -9,6 +11,8 @@ export interface DbOptions {
   verbose?: boolean;
   dbPath?: string;
   json?: boolean;
+  method?: string;
+  status?: number;
 }
 
 export async function dbCommand(options: DbOptions): Promise<number> {
@@ -58,11 +62,22 @@ export async function dbCommand(options: DbOptions): Promise<number> {
           else printError(msg);
           return 2;
         }
-        const detail = getRunDetail(id, options.verbose, options.dbPath);
-        if (json) {
-          printJson(jsonOk("db run", detail));
+        // If filtering by method/status, show filtered results instead of full detail
+        if (options.method || options.status !== undefined) {
+          getDb(options.dbPath);
+          const results = getFilteredResults(id, { method: options.method, status: options.status });
+          if (json) {
+            printJson(jsonOk("db run", { run_id: id, count: results.length, results }));
+          } else {
+            console.log(JSON.stringify({ run_id: id, count: results.length, results }, null, 2));
+          }
         } else {
-          console.log(JSON.stringify(detail, null, 2));
+          const detail = getRunDetail(id, options.verbose, options.dbPath);
+          if (json) {
+            printJson(jsonOk("db run", detail));
+          } else {
+            console.log(JSON.stringify(detail, null, 2));
+          }
         }
         return 0;
       }
@@ -75,7 +90,7 @@ export async function dbCommand(options: DbOptions): Promise<number> {
           else printError(msg);
           return 2;
         }
-        const result = diagnoseRun(id, options.verbose, options.dbPath);
+        const result = diagnoseRun(id, options.verbose, options.dbPath, options.limit);
         if (json) {
           printJson(jsonOk("db diagnose", result));
         } else {

package/src/cli/commands/describe.ts

@@ -1,4 +1,4 @@
-import { describeEndpoint, describeCompact } from "../../core/generator/describe.ts";
+import { describeEndpoint, describeCompact, describeAllParams } from "../../core/generator/describe.ts";
 import { printError } from "../output.ts";
 import { jsonOk, jsonError, printJson } from "../json-envelope.ts";
 
@@ -7,11 +7,36 @@ export interface DescribeOptions {
   method?: string;
   path?: string;
   compact?: boolean;
+  listParams?: boolean;
   json?: boolean;
 }
 
 export async function describeCommand(options: DescribeOptions): Promise<number> {
   try {
+    if (options.listParams) {
+      const params = await describeAllParams(options.specPath);
+      if (options.json) {
+        printJson(jsonOk("describe", { params }));
+      } else {
+        const grouped = new Map<string, typeof params>();
+        for (const p of params) {
+          const arr = grouped.get(p.in) ?? [];
+          arr.push(p);
+          grouped.set(p.in, arr);
+        }
+        for (const [location, locationParams] of grouped) {
+          console.log(`\n${location.toUpperCase()} parameters:`);
+          for (const p of locationParams) {
+            const req = p.required ? " (required)" : "";
+            const type = p.type ? ` [${p.type}]` : "";
+            console.log(`  ${p.name}${type}${req} — used in ${p.usedBy.length} endpoint(s)`);
+          }
+        }
+        console.log(`\n${params.length} unique parameter(s)`);
+      }
+      return 0;
+    }
+
     if (options.compact) {
       const endpoints = await describeCompact(options.specPath);
 

package/src/cli/commands/generate.ts

@@ -8,7 +8,7 @@ import {
   filterUncoveredEndpoints,
   serializeSuite,
 } from "../../core/generator/index.ts";
-import { generateSuites } from "../../core/generator/suite-generator.ts";
+import { generateSuites, findUnresolvedVars } from "../../core/generator/suite-generator.ts";
 import { filterByTag } from "../../core/generator/chunker.ts";
 import { parse } from "../../core/parser/yaml-parser.ts";
 import { decycleSchema } from "../../core/generator/schema-utils.ts";
@@ -104,12 +104,23 @@ export async function generateCommand(options: GenerateOptions): Promise<number>
       // DB unavailable — not fatal
     }
 
-    // Create .env.yaml with base_url if it doesn't exist
+    // Create .env.yaml with base_url and unresolved variables as placeholders
     const envPath = join(options.output, ".env.yaml");
     const envFile = Bun.file(envPath);
-    if (!(await envFile.exists()) && baseUrl) {
-      await Bun.write(envPath, `base_url: ${baseUrl}\n`);
-      warnings.push(`Created ${envPath} with base_url from spec`);
+    if (!(await envFile.exists())) {
+      const unresolvedVars = new Set<string>();
+      for (const suite of suites) {
+        for (const v of findUnresolvedVars(suite)) unresolvedVars.add(v);
+      }
+      const lines: string[] = [];
+      if (baseUrl) lines.push(`base_url: ${baseUrl}`);
+      for (const v of [...unresolvedVars].sort()) {
+        lines.push(`${v}: "" # TODO: fill in`);
+      }
+      if (lines.length > 0) {
+        await Bun.write(envPath, lines.join("\n") + "\n");
+        warnings.push(`Created ${envPath} with ${unresolvedVars.size} placeholder variable(s)`);
+      }
     }
 
     // Validate generated files

package/src/cli/commands/run.ts

@@ -2,7 +2,7 @@ import { dirname } from "path";
 import { stat } from "node:fs/promises";
 import { parse } from "../../core/parser/yaml-parser.ts";
 import { loadEnvironment } from "../../core/parser/variables.ts";
-import { filterSuitesByTags } from "../../core/parser/filter.ts";
+import { filterSuitesByTags, excludeSuitesByTags, filterSuitesByMethod } from "../../core/parser/filter.ts";
 import { runSuite } from "../../core/runner/executor.ts";
 import { getReporter } from "../../core/reporter/index.ts";
 import type { ReporterName } from "../../core/reporter/types.ts";
@@ -25,6 +25,8 @@ export interface RunOptions {
   authToken?: string;
   safe?: boolean;
   tag?: string[];
+  excludeTag?: string[];
+  method?: string;
   envVars?: string[];
   dryRun?: boolean;
   json?: boolean;
@@ -54,6 +56,24 @@ export async function runCommand(options: RunOptions): Promise<number> {
     }
   }
 
+  // 1b2. Exclude-tag filter
+  if (options.excludeTag && options.excludeTag.length > 0) {
+    suites = excludeSuitesByTags(suites, options.excludeTag);
+    if (suites.length === 0) {
+      printWarning("All suites excluded by --exclude-tag");
+      return 0;
+    }
+  }
+
+  // 1b3. Method filter
+  if (options.method) {
+    suites = filterSuitesByMethod(suites, options.method);
+    if (suites.length === 0) {
+      printWarning(`No tests found with method ${options.method.toUpperCase()}`);
+      return 0;
+    }
+  }
+
   // 1c. Safe mode: keep GET, set-only steps, and auth-related requests
   if (options.safe) {
     for (const suite of suites) {

package/src/cli/commands/update.ts

@@ -39,13 +39,13 @@ async function fetchLatestRelease(): Promise<GitHubRelease> {
 export async function updateCommand(options: UpdateOptions): Promise<number> {
   try {
     if (!isCompiledBinary()) {
-      const msg = "Self-update is only available for standalone binaries. Update via: npm update -g @kirrosh/zond  or  bun update -g @kirrosh/zond";
+      const msg = "Self-update is only available for standalone binaries. Install binary: curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh";
       if (options.json) {
-        printJson(jsonOk("update", { action: "skip", reason: "not-standalone" }, [msg]));
+        printJson(jsonOk("update", { action: "skip", reason: "not-standalone", installHint: "curl -fsSL https://raw.githubusercontent.com/kirrosh/zond/master/install.sh | sh" }, [msg]));
       } else {
         printWarning(msg);
       }
-      return 0;
+      return 3;
     }
 
     const target = getTarget();
@@ -141,16 +141,31 @@ export async function updateCommand(options: UpdateOptions): Promise<number> {
       }
 
       // Replace current binary
-      if (process.platform === "win32") {
-        // Windows: rename current to .old, move new, clean up
-        const oldBinary = currentBinary + ".old";
-        try { await rm(oldBinary, { force: true }); } catch {}
-        await rename(currentBinary, oldBinary);
-        await rename(newBinary, currentBinary);
-        try { await rm(oldBinary, { force: true }); } catch {}
-      } else {
-        await rename(newBinary, currentBinary);
-        await chmod(currentBinary, 0o755);
+      try {
+        if (process.platform === "win32") {
+          // Windows: rename current to .old, move new, clean up
+          const oldBinary = currentBinary + ".old";
+          try { await rm(oldBinary, { force: true }); } catch {}
+          await rename(currentBinary, oldBinary);
+          await rename(newBinary, currentBinary);
+          try { await rm(oldBinary, { force: true }); } catch {}
+        } else {
+          await rename(newBinary, currentBinary);
+          await chmod(currentBinary, 0o755);
+        }
+      } catch (replaceErr: any) {
+        if (replaceErr?.code === "EACCES" || replaceErr?.code === "EPERM") {
+          const hint = process.platform === "win32"
+            ? `Permission denied. Run the terminal as Administrator.`
+            : `Permission denied writing to ${currentBinary}. Run: sudo zond update`;
+          if (options.json) {
+            printJson(jsonError("update", [hint]));
+          } else {
+            printError(hint);
+          }
+          return 2;
+        }
+        throw replaceErr;
       }
 
       if (options.json) {

package/src/cli/index.ts

@@ -123,6 +123,8 @@ Options for 'run':
   --auth-token <token> Auth token injected as {{auth_token}} variable
   --safe               Run only GET tests (read-only, safe mode)
   --tag <tag>          Filter suites by tag (repeatable, comma-separated, OR logic)
+  --exclude-tag <tag>  Exclude suites by tag (repeatable, comma-separated)
+  --method <method>    Filter tests by HTTP method (e.g. GET, POST)
 
 Options for 'init':
   --name <name>        API name (auto-detected from spec title if omitted)
@@ -132,14 +134,15 @@ Options for 'init':
 
 Options for 'describe':
   --compact            List all endpoints briefly
+  --list-params        List all unique parameters across all endpoints
   --method <method>    HTTP method for single endpoint detail
   --path <path>        Endpoint path for single endpoint detail
 
 Options for 'db':
   zond db collections           List all API collections
   zond db runs [--limit N]      List recent test runs
-  zond db run <id> [--verbose]  Show run details
-  zond db diagnose <id>         Diagnose run failures
+  zond db run <id> [--verbose]  Show run details (--method GET, --status 403 to filter)
+  zond db diagnose <id>         Diagnose run failures (--limit N examples per group, --verbose for all)
   zond db compare <idA> <idB>   Compare two runs
 
 Options for 'request':
@@ -256,8 +259,9 @@ async function main(): Promise<number> {
         }
       }
 
-      // Collect all --tag and --env-var flags (parseArgs only stores last one, so re-parse)
+      // Collect all --tag, --exclude-tag, and --env-var flags (parseArgs only stores last one, so re-parse)
       const tagValues: string[] = [];
+      const excludeTagValues: string[] = [];
       const envVarValues: string[] = [];
       const rawRunArgs = process.argv.slice(2);
       for (let i = 0; i < rawRunArgs.length; i++) {
@@ -267,6 +271,11 @@ async function main(): Promise<number> {
           i++;
         } else if (arg.startsWith("--tag=")) {
           tagValues.push(arg.slice("--tag=".length));
+        } else if (arg === "--exclude-tag" && rawRunArgs[i + 1]) {
+          excludeTagValues.push(rawRunArgs[i + 1]!);
+          i++;
+        } else if (arg.startsWith("--exclude-tag=")) {
+          excludeTagValues.push(arg.slice("--exclude-tag=".length));
         } else if (arg === "--env-var" && rawRunArgs[i + 1]) {
           envVarValues.push(rawRunArgs[i + 1]!);
           i++;
@@ -276,6 +285,7 @@ async function main(): Promise<number> {
       }
       // Support comma-separated: --tag smoke,crud → ["smoke", "crud"]
       const tags = tagValues.flatMap(v => v.split(",")).filter(Boolean);
+      const excludeTags = excludeTagValues.flatMap(v => v.split(",")).filter(Boolean);
 
       return runCommand({
         path,
@@ -288,6 +298,8 @@ async function main(): Promise<number> {
         authToken: typeof flags["auth-token"] === "string" ? flags["auth-token"] : undefined,
         safe: flags["safe"] === true,
         tag: tags.length > 0 ? tags : undefined,
+        excludeTag: excludeTags.length > 0 ? excludeTags : undefined,
+        method: typeof flags["method"] === "string" ? flags["method"] : undefined,
         envVars: envVarValues.length > 0 ? envVarValues : undefined,
         dryRun: flags["dry-run"] === true,
         json: jsonFlag,
@@ -410,6 +422,7 @@ async function main(): Promise<number> {
       return describeCommand({
         specPath,
         compact: flags["compact"] === true,
+        listParams: flags["list-params"] === true,
         method: typeof flags["method"] === "string" ? flags["method"] : undefined,
         path: typeof flags["path"] === "string" ? flags["path"] : undefined,
         json: jsonFlag,
@@ -428,6 +441,13 @@ async function main(): Promise<number> {
         limit = parseInt(limitRaw, 10);
         if (isNaN(limit) || limit <= 0) limit = undefined;
       }
+      const statusRaw = flags["status"];
+      let statusFilter: number | undefined;
+      if (typeof statusRaw === "string") {
+        statusFilter = parseInt(statusRaw, 10);
+        if (isNaN(statusFilter)) statusFilter = undefined;
+      }
+
       return dbCommand({
         subcommand: dbSub,
         positional: positional.slice(1),
@@ -435,6 +455,8 @@ async function main(): Promise<number> {
         verbose: flags["verbose"] === true,
         dbPath: typeof flags["db"] === "string" ? flags["db"] : undefined,
         json: jsonFlag,
+        method: typeof flags["method"] === "string" ? flags["method"] : undefined,
+        status: statusFilter,
       });
     }
 

package/src/core/diagnostics/db-analysis.ts

@@ -169,7 +169,7 @@ export interface DiagnoseResult {
   grouped_failures?: FailureGroup[];
 }
 
-export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string): DiagnoseResult {
+export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string, maxExamples?: number): DiagnoseResult {
   getDb(dbPath);
   const diagRun = getRunById(runId);
   if (!diagRun) throw new Error(`Run ${runId} not found`);
@@ -272,7 +272,7 @@ export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string):
 
   const { grouped_failures, compactFailures } = verbose
     ? { grouped_failures: undefined, compactFailures: failures }
-    : groupFailures(failures);
+    : groupFailures(failures, maxExamples);
 
   return {
     run: {
@@ -301,7 +301,7 @@ export function diagnoseRun(runId: number, verbose?: boolean, dbPath?: string):
 type FailureItem = { suite_name: string; test_name: string; failure_type: string; recommended_action: RecommendedAction; hint?: string; response_status: number | null };
 
 /** Group similar failures for compact output. Exported for testing. */
-export function groupFailures<T extends FailureItem>(failures: T[]): { grouped_failures?: FailureGroup[]; compactFailures: T[] } {
+export function groupFailures<T extends FailureItem>(failures: T[], maxExamples = 2): { grouped_failures?: FailureGroup[]; compactFailures: T[] } {
   if (failures.length <= 5) {
     return { compactFailures: failures };
   }
@@ -341,7 +341,7 @@ export function groupFailures<T extends FailureItem>(failures: T[]): { grouped_f
       failure_type: group.failure_type,
       recommended_action: group.items[0]!.recommended_action,
       hint: group.hint,
-      examples: group.items.slice(0, 2).map(f => `${f.suite_name}/${f.test_name}`),
+      examples: (maxExamples === 0 ? group.items : group.items.slice(0, maxExamples)).map(f => `${f.suite_name}/${f.test_name}`),
       response_status: group.response_status,
     });
     compactFailures.push(group.items[0]!);

package/src/core/generator/describe.ts

@@ -248,3 +248,55 @@ export async function describeCompact(
 
   return result;
 }
+
+export interface ParamInfo {
+  name: string;
+  in: string;
+  type?: string;
+  required: boolean;
+  usedBy: string[];
+}
+
+export async function describeAllParams(
+  specPath: string,
+  options?: { insecure?: boolean },
+): Promise<ParamInfo[]> {
+  const doc = await readOpenApiSpec(specPath, options) as OpenAPIV3.Document;
+  const paths = doc.paths ?? {};
+  const paramMap = new Map<string, ParamInfo>();
+
+  for (const [path, pathItem] of Object.entries(paths)) {
+    const pathParams = ((pathItem as any)?.parameters ?? []) as OpenAPIV3.ParameterObject[];
+
+    for (const method of ["get", "post", "put", "patch", "delete"]) {
+      const op = (pathItem as any)?.[method] as OpenAPIV3.OperationObject | undefined;
+      if (!op) continue;
+
+      const allParams = [...pathParams, ...((op.parameters ?? []) as OpenAPIV3.ParameterObject[])];
+      const endpoint = `${method.toUpperCase()} ${path}`;
+
+      for (const p of allParams) {
+        const key = `${p.in}:${p.name}`;
+        const existing = paramMap.get(key);
+        const schema = p.schema as OpenAPIV3.SchemaObject | undefined;
+        if (existing) {
+          existing.usedBy.push(endpoint);
+          if (p.required) existing.required = true;
+        } else {
+          paramMap.set(key, {
+            name: p.name,
+            in: p.in,
+            type: schema?.type,
+            required: p.required ?? false,
+            usedBy: [endpoint],
+          });
+        }
+      }
+    }
+  }
+
+  return [...paramMap.values()].sort((a, b) => {
+    if (a.in !== b.in) return a.in.localeCompare(b.in);
+    return a.name.localeCompare(b.name);
+  });
+}

package/src/core/generator/endpoint-warnings.ts

@@ -1,6 +1,6 @@
 import type { EndpointInfo } from "./types.ts";
 
-export type WarningCode = "deprecated" | "no_response_schema" | "no_responses_defined" | "required_params_no_examples";
+export type WarningCode = "deprecated" | "no_response_schema" | "no_responses_defined" | "required_params_no_examples" | "post_body_as_query";
 
 export interface EndpointWarning {
   method: string;
@@ -34,6 +34,15 @@ export function analyzeEndpoints(endpoints: EndpointInfo[]): EndpointWarning[] {
       warnings.push(`required_params_no_examples: ${missingExamples.join(", ")}`);
     }
 
+    // SpringDoc quirk: POST/PUT/PATCH with query param named "body" or single complex object query param
+    if (["POST", "PUT", "PATCH"].includes(ep.method)) {
+      const queryParams = ep.parameters.filter(p => p.in === "query");
+      const hasBodyQuery = queryParams.some(p => p.name.toLowerCase() === "body");
+      if (hasBodyQuery) {
+        warnings.push("post_body_as_query: query param 'body' on POST/PUT/PATCH likely means request body (SpringDoc quirk)");
+      }
+    }
+
     if (warnings.length > 0) {
       result.push({ method: ep.method, path: ep.path, warnings });
     }

package/src/core/generator/suite-generator.ts

@@ -15,8 +15,8 @@ function convertPath(path: string): string {
 
 /**
  * Convert path params to seed values for smoke suites (no capture context).
- * Uses the parameter's example/default from the spec, or falls back to "1" for
- * id-like params. Non-id string params keep the {{placeholder}} form.
+ * Uses the parameter's example/default from the spec, or falls back to
+ * {{placeholder}} form so the user fills them in via .env.yaml.
  */
 function convertPathWithSeeds(path: string, ep: EndpointInfo): string {
   return path.replace(/\{([^}]+)\}/g, (_, name: string) => {
@@ -24,7 +24,6 @@ function convertPathWithSeeds(path: string, ep: EndpointInfo): string {
     const schema = param?.schema as OpenAPIV3.SchemaObject | undefined;
     const example = (param as any)?.example ?? schema?.example ?? schema?.default;
     if (example !== undefined) return String(example);
-    if (schema?.type === "integer" || /^id$|_id$|Id$/i.test(name)) return "1";
     return `{{${name}}}`;
   });
 }
@@ -81,6 +80,20 @@ function getBodyAssertions(ep: EndpointInfo): Record<string, Record<string, stri
   return undefined;
 }
 
+/** Derive a variable name for a security scheme's token */
+function schemeVarName(scheme: SecuritySchemeInfo, allSchemes: SecuritySchemeInfo[]): string {
+  // Count how many bearer-like schemes exist
+  const bearerSchemes = allSchemes.filter(s =>
+    (s.type === "http" && (s.scheme === "bearer" || !s.scheme)) ||
+    (s.type === "apiKey" && s.in === "header" && s.apiKeyName === "Authorization")
+  );
+  // If only one bearer scheme → keep generic auth_token for backward compat
+  if (bearerSchemes.length <= 1) return "auth_token";
+  // Multiple → derive from scheme name (e.g. "platformAuth" → "platform_auth_token")
+  const slug = scheme.name.replace(/([a-z])([A-Z])/g, "$1_$2").toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/_token$|_auth$/, "");
+  return `${slug}_token`;
+}
+
 function getAuthHeaders(
   ep: EndpointInfo,
   schemes: SecuritySchemeInfo[],
@@ -93,16 +106,15 @@ function getAuthHeaders(
 
     if (scheme.type === "http") {
       if (scheme.scheme === "bearer" || !scheme.scheme) {
-        return { Authorization: "Bearer {{auth_token}}" };
+        return { Authorization: `Bearer {{${schemeVarName(scheme, schemes)}}}` };
       }
       if (scheme.scheme === "basic") {
-        return { Authorization: "Basic {{auth_token}}" };
+        return { Authorization: `Basic {{${schemeVarName(scheme, schemes)}}}` };
       }
     }
     if (scheme.type === "apiKey" && scheme.in === "header" && scheme.apiKeyName) {
-      // When apiKey scheme uses Authorization header, it's typically a Bearer token
       if (scheme.apiKeyName === "Authorization") {
-        return { Authorization: "Bearer {{auth_token}}" };
+        return { Authorization: `Bearer {{${schemeVarName(scheme, schemes)}}}` };
       }
       return { [scheme.apiKeyName]: "{{api_key}}" };
     }
@@ -111,14 +123,15 @@ function getAuthHeaders(
   return undefined;
 }
 
-function getRequiredQueryParams(ep: EndpointInfo): Record<string, unknown> | undefined {
+function getRequiredQueryParams(ep: EndpointInfo): Record<string, string> | undefined {
   const queryParams = ep.parameters.filter(p => p.in === "query" && p.required);
   if (queryParams.length === 0) return undefined;
 
-  const query: Record<string, unknown> = {};
+  const query: Record<string, string> = {};
   for (const p of queryParams) {
     if (p.schema) {
-      query[p.name] = generateFromSchema(p.schema as OpenAPIV3.SchemaObject, p.name);
+      const val = generateFromSchema(p.schema as OpenAPIV3.SchemaObject, p.name);
+      query[p.name] = typeof val === "object" ? JSON.stringify(val) : String(val);
     } else {
       query[p.name] = "{{$randomString}}";
     }
@@ -387,9 +400,10 @@ export function generateCrudSuite(
 }
 
 /** Find unresolved template variables in a suite (excluding known globals, captured vars, and env keys) */
-export function findUnresolvedVars(suite: RawSuite, envKeys?: Set<string>): string[] {
+export function findUnresolvedVars(suite: RawSuite, envKeys?: Set<string>, extraKnown?: Set<string>): string[] {
   const KNOWN = new Set(["base_url", "auth_token", "api_key"]);
   if (envKeys) for (const k of envKeys) KNOWN.add(k);
+  if (extraKnown) for (const k of extraKnown) KNOWN.add(k);
   const captured = new Set<string>();
   for (const step of suite.tests) {
     if (step.expect?.body) {
@@ -518,8 +532,13 @@ function generateConsistentAuthSuite(
       /token|access_token|accessToken|jwt/i.test(k)
     );
     if (tokenField) {
+      // Determine the capture variable name based on the login endpoint's security scheme
+      const loginScheme = loginEp.security.length > 0
+        ? securitySchemes.find(s => s.name === loginEp.security[0])
+        : undefined;
+      const captureVar = loginScheme ? schemeVarName(loginScheme, securitySchemes) : "auth_token";
       if (!loginStep.expect.body) loginStep.expect.body = {};
-      loginStep.expect.body[tokenField] = { capture: "auth_token" };
+      loginStep.expect.body[tokenField] = { capture: captureVar };
     }
   }
   tests.push(loginStep);

package/src/core/parser/filter.ts

@@ -12,3 +12,29 @@ export function filterSuitesByTags(suites: TestSuite[], tags: string[]): TestSui
     return suite.tags.some(t => normalizedTags.includes(t.toLowerCase()));
   });
 }
+
+/**
+ * Exclude suites whose tags intersect with the exclusion set (OR logic, case-insensitive).
+ * Suites without tags are kept.
+ */
+export function excludeSuitesByTags(suites: TestSuite[], excludeTags: string[]): TestSuite[] {
+  if (excludeTags.length === 0) return suites;
+  const normalizedTags = excludeTags.map(t => t.toLowerCase());
+  return suites.filter(suite => {
+    if (!suite.tags || suite.tags.length === 0) return true;
+    return !suite.tags.some(t => normalizedTags.includes(t.toLowerCase()));
+  });
+}
+
+/**
+ * Filter test steps within suites by HTTP method (case-insensitive).
+ * Suites with no remaining tests are removed.
+ */
+export function filterSuitesByMethod(suites: TestSuite[], method: string): TestSuite[] {
+  const upperMethod = method.toUpperCase();
+  const filtered = suites.map(suite => ({
+    ...suite,
+    tests: suite.tests.filter(t => (t.method ?? "GET").toUpperCase() === upperMethod),
+  }));
+  return filtered.filter(s => s.tests.length > 0);
+}

package/src/db/queries.ts

@@ -255,7 +255,9 @@ export function saveResults(runId: number, suiteResults: TestRunResult[]): void
   db.transaction(() => {
     for (const suite of suiteResults) {
       for (const step of suite.steps) {
-        const keepBody = step.status === "fail" || step.status === "error";
+        const maxBodySize = 50_000;
+        const truncBody = (s: string | null | undefined) =>
+          s && s.length > maxBodySize ? s.slice(0, maxBodySize) + "\n...[truncated]" : (s ?? null);
         stmt.run({
           $run_id: runId,
           $suite_name: suite.suite_name,
@@ -264,10 +266,10 @@ export function saveResults(runId: number, suiteResults: TestRunResult[]): void
           $duration_ms: step.duration_ms,
           $request_method: step.request.method,
           $request_url: step.request.url,
-          $request_body: step.request.body ?? null,
+          $request_body: truncBody(step.request.body),
           $response_status: step.response?.status ?? null,
-          $response_body: keepBody ? (step.response?.body ?? null) : null,
-          $response_headers: keepBody && step.response?.headers
+          $response_body: truncBody(step.response?.body),
+          $response_headers: step.response?.headers
             ? JSON.stringify(step.response.headers)
             : null,
           $error_message: step.error ?? null,
@@ -292,6 +294,30 @@ export function getResultsByRunId(runId: number): StoredStepResult[] {
   }));
 }
 
+export function getFilteredResults(runId: number, filters: { method?: string; status?: number }): StoredStepResult[] {
+  const db = getDb();
+  const conditions = ["run_id = ?"];
+  const params: (string | number)[] = [runId];
+
+  if (filters.method) {
+    conditions.push("request_method = ?");
+    params.push(filters.method.toUpperCase());
+  }
+  if (filters.status !== undefined) {
+    conditions.push("response_status = ?");
+    params.push(filters.status);
+  }
+
+  const rows = db.query(`SELECT * FROM results WHERE ${conditions.join(" AND ")} ORDER BY id`).all(...params) as Array<
+    Omit<StoredStepResult, "assertions" | "captures"> & { assertions: string | null; captures: string | null }
+  >;
+  return rows.map((row) => ({
+    ...row,
+    assertions: row.assertions ? JSON.parse(row.assertions) : [],
+    captures: row.captures ? JSON.parse(row.captures) : {},
+  }));
+}
+
 // ──────────────────────────────────────────────
 // Dashboard metrics
 // ──────────────────────────────────────────────

package/src/web/data/collection-state.ts

@@ -40,6 +40,7 @@ export interface StepViewState {
   durationMs?: number;
   requestMethod?: string;
   requestUrl?: string;
+  requestBody?: string;
   responseStatus?: number;
   responseBody?: string;
   assertions?: { field: string; rule: string; passed: boolean; actual?: unknown; expected?: unknown }[];
@@ -281,6 +282,7 @@ export async function buildCollectionState(collection: CollectionRecord): Promis
           durationMs: r.duration_ms ?? undefined,
           requestMethod: r.request_method ?? undefined,
           requestUrl: r.request_url ?? undefined,
+          requestBody: r.request_body ?? undefined,
           responseStatus: r.response_status ?? undefined,
           responseBody: r.response_body ?? undefined,
           assertions: Array.isArray(r.assertions) ? r.assertions : undefined,

package/src/web/routes/dashboard.ts

@@ -253,6 +253,28 @@ async function renderCollectionContent(collection: CollectionRecord): Promise<st
       document.querySelectorAll('.tab-btn').forEach(b => b.classList.remove('tab-active'));
       el.classList.add('tab-active');
     }
+    function switchToSuite(suiteName) {
+      var suitesBtn = document.querySelector('[data-tab="suites"]');
+      if (!suitesBtn) return;
+      suitesBtn.click();
+      document.addEventListener('htmx:afterSwap', function handler(e) {
+        if (e.detail.target && e.detail.target.id === 'tab-content') {
+          document.removeEventListener('htmx:afterSwap', handler);
+          setTimeout(function() {
+            var rows = document.querySelectorAll('.suite-row[data-suite-name]');
+            for (var i = 0; i < rows.length; i++) {
+              if (rows[i].dataset.suiteName === suiteName) {
+                rows[i].scrollIntoView({ behavior: 'smooth', block: 'center' });
+                rows[i].click();
+                rows[i].classList.add('suite-highlight');
+                setTimeout(function() { rows[i].classList.remove('suite-highlight'); }, 2000);
+                break;
+              }
+            }
+          }, 50);
+        }
+      });
+    }
   </script>`;
 
   return `

package/src/web/static/style.css

@@ -816,6 +816,37 @@ h3 { font-size: 1.05rem; margin: 1rem 0 0.25rem; }
 .history-row:hover { background: var(--bg-hover); }
 .pagination { display: flex; gap: 0.5rem; margin: 1.5rem 0; align-items: center; }
 
+/* ── Step method+path+status labels ── */
+.step-path { font-family: var(--font-mono); font-size: 0.8rem; }
+.step-status-code {
+  display: inline-block;
+  font-family: var(--font-mono);
+  font-size: 0.65rem;
+  font-weight: 600;
+  padding: 0.1rem 0.35rem;
+  border-radius: 3px;
+  margin-left: 0.35rem;
+  vertical-align: middle;
+}
+.step-status-code.status-ok { background: var(--pass-dim); color: var(--pass); }
+.step-status-code.status-error { background: var(--fail-dim); color: var(--fail); }
+.step-name-dim { color: var(--text-dim); font-size: 0.7rem; margin-left: 0.5rem; }
+
+/* ── Suite link (endpoints → suites navigation) ── */
+.suite-link {
+  color: var(--accent);
+  text-decoration: none;
+  cursor: pointer;
+}
+.suite-link:hover { text-decoration: underline; }
+.suite-highlight {
+  animation: suite-flash 2s ease-out;
+}
+@keyframes suite-flash {
+  0% { background: rgba(61, 139, 253, 0.25); }
+  100% { background: transparent; }
+}
+
 /* ── Responsive ── */
 @media (max-width: 768px) {
   .health-strip { grid-template-columns: 1fr; gap: 1rem; }

package/src/web/views/endpoints-tab.ts

@@ -93,7 +93,7 @@ function renderWarningBadges(warnings: string[]): string {
     if (w === "deprecated") return '<span class="warning-badge warning-deprecated">DEPRECATED</span>';
     if (w === "no_response_schema") return '<span class="warning-badge warning-schema">NO SCHEMA</span>';
     if (w === "no_responses_defined") return '<span class="warning-badge warning-schema">NO RESPONSES</span>';
-    if (w.startsWith("required_params_no_examples")) return '<span class="warning-badge warning-params">MISSING EXAMPLES</span>';
+    if (w.startsWith("required_params_no_examples")) return "";
     return `<span class="warning-badge">${escapeHtml(w)}</span>`;
   }).join(" ");
 }
@@ -140,7 +140,8 @@ function renderEndpointDetail(ep: EndpointViewState): string {
 
       return `<div class="covering-suite">
         ${icon}
-        <span class="suite-ref">${escapeHtml(step.file)}</span>
+        <a class="suite-ref suite-link" href="#" data-suite="${escapeHtml(step.suiteName)}"
+           onclick="event.stopPropagation();switchToSuite(this.dataset.suite)">${escapeHtml(step.file)}</a>
         <span class="dim" style="font-size:0.75rem;">&rarr; "${escapeHtml(step.stepName)}"</span>
         <span style="margin-left:auto;display:flex;align-items:center;gap:0.5rem;">${statusBadge}${duration}</span>
       </div>${assertionsHtml}${hintHtml}`;
@@ -149,13 +150,16 @@ function renderEndpointDetail(ep: EndpointViewState): string {
   }
 
   // Fallback: just file names
-  const files = ep.coveringFiles.map(f =>
-    `<div class="covering-suite">
+  const files = ep.coveringFiles.map(f => {
+    const fileName = basename(f);
+    const suiteName = fileName.replace(/\.(ya?ml)$/i, "");
+    return `<div class="covering-suite">
       <span class="step-icon" style="color:var(--text-dim);">&#9675;</span>
-      <span class="suite-ref">${escapeHtml(basename(f))}</span>
+      <a class="suite-ref suite-link" href="#" data-suite="${escapeHtml(suiteName)}"
+         onclick="event.stopPropagation();switchToSuite(this.dataset.suite)">${escapeHtml(fileName)}</a>
       <span class="dim" style="font-size:0.75rem;">not run</span>
-    </div>`
-  ).join("");
+    </div>`;
+  }).join("");
   return files;
 }
 

package/src/web/views/results.ts

@@ -98,11 +98,11 @@ export function renderSuiteResults(
         }
 
         let reqBodyHtml = "";
-        if (hasFailed && step.request_body) {
+        if (step.request_body) {
           reqBodyHtml = `<details class="body-details"><summary>Request Body</summary><pre>${escapeHtml(step.request_body)}</pre></details>`;
         }
         let resBodyHtml = "";
-        if (hasFailed && step.response_body) {
+        if (step.response_body) {
           resBodyHtml = `<details class="body-details"><summary>Response Body</summary><pre>${escapeHtml(step.response_body)}</pre></details>`;
         }
 
@@ -123,7 +123,8 @@ export function renderSuiteResults(
           }
         }
 
-        const detailPanel = (hasFailed || skipReasonHtml)
+        const hasContent = requestHtml || errorHtml || skipReasonHtml || assertionsHtml || reqBodyHtml || resBodyHtml;
+        const detailPanel = hasContent
           ? `<div class="detail-panel" id="${detailId}" style="display:none">
               ${requestHtml}
               ${errorHtml}
@@ -134,7 +135,7 @@ export function renderSuiteResults(
             </div>`
           : "";
 
-        const toggle = (hasFailed || skipReasonHtml)
+        const toggle = hasContent
           ? `onclick="var d=document.getElementById('${detailId}');d.style.display=d.style.display==='none'?'block':'none'"`
           : "";
 
@@ -144,7 +145,7 @@ export function renderSuiteResults(
         return `
           <div class="step-row${chainedClass}${statusClass}" ${toggle}>
             <div>${stepStatusBadge(step.status)}</div>
-            <div class="step-name">${escapeHtml(step.test_name)}${capturesHtml ? ` ${capturesHtml}` : ""}</div>
+            <div class="step-name">${step.request_method && step.request_url ? (() => { let p: string; try { p = new URL(step.request_url).pathname; } catch { p = step.request_url; } const sc = step.response_status ? ` <span class="step-status-code ${step.response_status >= 400 ? "status-error" : "status-ok"}">${step.response_status}</span>` : ""; return `${methodBadge(step.request_method)} <span class="step-path">${escapeHtml(p)}</span>${sc} <span class="step-name-dim">${escapeHtml(step.test_name)}</span>`; })() : escapeHtml(step.test_name)}${capturesHtml ? ` ${capturesHtml}` : ""}</div>
             <div class="step-duration">${formatDuration(step.duration_ms)}</div>
           </div>
           ${detailPanel}`;

package/src/web/views/suites-tab.ts

@@ -4,6 +4,7 @@
 
 import type { CollectionState, SuiteViewState, StepViewState } from "../data/collection-state.ts";
 import { escapeHtml } from "./layout.ts";
+import { methodBadge } from "./results.ts";
 import { basename } from "node:path";
 
 export function renderSuitesTab(state: CollectionState): string {
@@ -55,7 +56,7 @@ function renderSuiteRow(suite: SuiteViewState, index: number): string {
     : `<div style="font-size:0.75rem;color:var(--text-dim);padding:0.5rem;">No run results yet</div>`;
 
   return `
-    <div class="suite-row"
+    <div class="suite-row" data-suite-name="${escapeHtml(suite.name)}"
       onclick="var d=document.getElementById('${detailId}');d.style.display=d.style.display==='none'?'block':'none'">
       <div class="suite-info">
         <div class="suite-name">${escapeHtml(suite.name)}</div>
@@ -87,6 +88,21 @@ function renderStepRow(step: StepViewState, suiteIdx: number, stepIdx: number):
     ? `<span class="step-duration">${step.durationMs}ms</span>`
     : `<span class="step-duration">-</span>`;
 
+  // Primary label: prefer METHOD /path [status] over step name
+  let primaryLabel: string;
+  let nameLabel = "";
+  if (step.requestMethod && step.requestUrl) {
+    let urlPath: string;
+    try { urlPath = new URL(step.requestUrl).pathname; } catch { urlPath = step.requestUrl; }
+    const statusTag = step.responseStatus
+      ? ` <span class="step-status-code ${step.responseStatus >= 400 ? "status-error" : "status-ok"}">${step.responseStatus}</span>`
+      : "";
+    primaryLabel = `${methodBadge(step.requestMethod)} <span class="step-path">${escapeHtml(urlPath)}</span>${statusTag}`;
+    nameLabel = ` <span class="step-name-dim">${escapeHtml(step.name)}</span>`;
+  } else {
+    primaryLabel = escapeHtml(step.name);
+  }
+
   // Captures
   const captureHtml = step.captures && Object.keys(step.captures).length > 0
     ? `<span class="step-captures">${Object.entries(step.captures).map(([k, v]) =>
@@ -95,8 +111,13 @@ function renderStepRow(step: StepViewState, suiteIdx: number, stepIdx: number):
     : `<span class="step-captures"></span>`;
 
   const detailId = `s-${suiteIdx}-step-${stepIdx}`;
-  const hasDetail = (step.status === "fail" || step.status === "error") &&
-    ((step.assertions && step.assertions.length > 0) || step.hint || step.responseBody);
+  const hasDetail =
+    (step.assertions && step.assertions.length > 0) ||
+    step.hint ||
+    step.responseBody ||
+    step.requestBody ||
+    step.errorMessage ||
+    (step.requestMethod && step.requestUrl);
 
   const clickHandler = hasDetail
     ? ` onclick="event.stopPropagation();var d=document.getElementById('${detailId}');d.style.display=d.style.display==='none'?'block':'none'"`
@@ -134,6 +155,13 @@ function renderStepRow(step: StepViewState, suiteIdx: number, stepIdx: number):
       detailContent += `<div class="failure-hint"><span>&#9888;</span> ${escapeHtml(step.hint)}</div>`;
     }
 
+    // Request body toggle
+    if (step.requestBody) {
+      const truncatedReq = step.requestBody.length > 2000 ? step.requestBody.slice(0, 2000) + "..." : step.requestBody;
+      detailContent += `<div class="req-res-toggle" onclick="event.stopPropagation();var b=this.nextElementSibling;b.style.display=b.style.display==='none'?'block':'none'">&#9660; Request Body</div>
+        <div class="req-res-body" style="display:none;"><pre style="font-size:0.7rem;margin:0.25rem 0;">${escapeHtml(truncatedReq)}</pre></div>`;
+    }
+
     // Response body toggle
     if (step.responseBody) {
       const truncated = step.responseBody.length > 2000 ? step.responseBody.slice(0, 2000) + "..." : step.responseBody;
@@ -146,7 +174,7 @@ function renderStepRow(step: StepViewState, suiteIdx: number, stepIdx: number):
 
   return `<div class="step-row"${clickHandler}>
     ${icon}
-    <span class="step-label"${labelStyle}>${escapeHtml(step.name)}</span>
+    <span class="step-label"${labelStyle}>${primaryLabel}${nameLabel}</span>
     ${captureHtml}
     ${duration}
   </div>${detailPanel}`;