Add enhanced TUI guidance: pre-flight checklist, step descriptions, live warnings, next-steps

- Step description banners before each scan step explain what's being tested
- Pre-flight checklist validates setup (resolvers, workers, binaries, NS delegation reminder)
- Live pass-rate warning during scan when rate drops below 5%
- Inter-step summary shows pass rate and resolver count advancing
- Post-scan next-steps guidance (test command, e2e suggestion, guide link)

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: SamNet-dev

cmd/root.go

@@ -179,6 +179,70 @@ func newProgressFactoryWithTotal(total int) scanner.ProgressFactory {
 	}
 }
 
+func newScanProgressFactory(totalSteps int, descriptions map[string]string) scanner.ProgressFactory {
+	if !isTTY() {
+		return nil
+	}
+	stepNum := 0
+	return func(stepName string) scanner.ProgressFunc {
+		stepNum++
+		label := fmt.Sprintf("[%d/%d] %s", stepNum, totalSteps, stepName)
+
+		// Print step description banner
+		w := os.Stderr
+		if desc, ok := descriptions[stepName]; ok {
+			fmt.Fprintf(w, "  %s── %s ─────────────────────────────────%s\n", colorDim, desc, colorReset)
+		}
+
+		start := time.Now()
+		warnedLow := false
+
+		return func(done, total, passed, failed int) {
+			if total == 0 {
+				return
+			}
+			pct := done * 100 / total
+			elapsed := time.Since(start).Truncate(time.Second)
+			bar := progressBar(pct, 20)
+			fmt.Fprintf(w, "\r\033[2K  \033[1m%s\033[0m  %s  %d/%d  \033[32m%d \u2714\033[0m  \033[31m%d \u2718\033[0m  \033[2m%s\033[0m",
+				label, bar, done, total, passed, failed, elapsed)
+
+			// Live warning: after 25% done with enough samples, if pass rate < 5%
+			if !warnedLow && done > 20 && done >= total/4 {
+				rate := passed * 100 / done
+				if rate < 5 {
+					warnedLow = true
+					fmt.Fprintf(w, "\n  %s\u26a0 Very low pass rate (%d%%) — check configuration%s\n", colorYellow, rate, colorReset)
+				}
+			}
+
+			// Completion: inter-step summary
+			if done == total {
+				elapsed = time.Since(start).Truncate(time.Second)
+				passRate := 0
+				if total > 0 {
+					passRate = passed * 100 / total
+				}
+				color := colorGreen
+				if passRate < 50 {
+					color = colorYellow
+				}
+				if passRate < 20 {
+					color = colorRed
+				}
+				fmt.Fprintf(w, "\r\033[2K  %s\u2714%s %-18s  %s%d/%d passed (%d%%)%s  %s%s%s\n",
+					color, colorReset,
+					stepName,
+					color, passed, total, passRate, colorReset,
+					colorDim, elapsed, colorReset)
+				if stepNum < totalSteps && passed > 0 {
+					fmt.Fprintf(w, "  %s\u21b3 %d resolvers advancing to next step%s\n", colorDim, passed, colorReset)
+				}
+			}
+		}
+	}
+}
+
 func progressBar(pct, width int) string {
 	filled := pct * width / 100
 	bar := make([]rune, width)

cmd/scan.go

@@ -24,6 +24,19 @@ const (
 	colorWhite  = "\033[37m"
 )
 
+var stepDescriptions = map[string]string{
+	"ping":               "Testing ICMP reachability of resolvers",
+	"resolve":            "Checking if resolvers can resolve standard domains",
+	"nxdomain":           "Detecting DNS hijacking on non-existent domains",
+	"edns":               "Testing EDNS0 support and buffer sizes",
+	"resolve/tunnel":     "Verifying resolvers forward queries to your tunnel domain",
+	"e2e/dnstt":          "Full tunnel connectivity test via DNSTT",
+	"e2e/slipstream":     "Full tunnel connectivity test via Slipstream",
+	"doh/resolve":        "Checking DoH resolver connectivity",
+	"doh/resolve/tunnel": "Verifying DoH resolvers forward to your tunnel domain",
+	"doh/e2e":            "Full DoH tunnel connectivity test via DNSTT",
+}
+
 var scanCmd = &cobra.Command{
 	Use:   "scan",
 	Short: "Full scan pipeline: ping -> resolve -> nxdomain -> tunnel -> e2e",
@@ -168,19 +181,20 @@ func runScan(cmd *cobra.Command, args []string) error {
 	}
 
 	printBanner(len(ips), dohMode, domain, steps)
+	printPreFlight(len(ips), domain, dnsttBin, slipstreamBin, steps)
 
 	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt)
 	defer stop()
 
 	scanStart := time.Now()
-	report := scanner.RunChainQuietCtx(ctx, ips, workers, steps, newProgressFactoryWithTotal(len(steps)))
+	report := scanner.RunChainQuietCtx(ctx, ips, workers, steps, newScanProgressFactory(len(steps), stepDescriptions))
 	totalTime := time.Since(scanStart)
 
 	if ctx.Err() != nil {
 		fmt.Fprintf(os.Stderr, "\n\n  %s⚠ Interrupted — saving partial results to %s%s\n", colorYellow, outputFile, colorReset)
 	}
 
-	printSummary(report, topN, totalTime)
+	printSummary(report, topN, totalTime, domain)
 
 	return scanner.WriteChainReport(report, outputFile)
 }
@@ -196,6 +210,29 @@ func hline(left, fill, right string, width int) string {
 	return left + strings.Repeat(fill, width) + right
 }
 
+func printPreFlight(ipCount int, domain, dnsttBin, slipstreamBin string, steps []scanner.Step) {
+	if !isTTY() {
+		return
+	}
+	w := os.Stderr
+	fmt.Fprintf(w, "  %sPre-flight:%s\n", colorBold, colorReset)
+	fmt.Fprintf(w, "    %s\u2714%s %d resolvers loaded\n", colorGreen, colorReset, ipCount)
+	fmt.Fprintf(w, "    %s\u2714%s %d workers\n", colorGreen, colorReset, workers)
+	fmt.Fprintf(w, "    %s\u2714%s %d scan steps configured\n", colorGreen, colorReset, len(steps))
+	if dnsttBin != "" {
+		fmt.Fprintf(w, "    %s\u2714%s dnstt-client: %s%s%s\n", colorGreen, colorReset, colorDim, dnsttBin, colorReset)
+	}
+	if slipstreamBin != "" {
+		fmt.Fprintf(w, "    %s\u2714%s slipstream-client: %s%s%s\n", colorGreen, colorReset, colorDim, slipstreamBin, colorReset)
+	}
+	if domain != "" {
+		fmt.Fprintf(w, "    %s\u26a0%s Domain: %s%s%s — %sverify NS delegation before scanning%s\n",
+			colorYellow, colorReset, colorCyan, domain, colorReset, colorDim, colorReset)
+		fmt.Fprintf(w, "      %snslookup -type=NS %s 8.8.8.8%s\n", colorDim, domain, colorReset)
+	}
+	fmt.Fprintf(w, "\n")
+}
+
 func printBanner(count int, doh bool, domain string, steps []scanner.Step) {
 	mode := "UDP"
 	if doh {
@@ -232,7 +269,7 @@ func printBanner(count int, doh bool, domain string, steps []scanner.Step) {
 	fmt.Fprintf(w, "\n\n")
 }
 
-func printSummary(report scanner.ChainReport, topN int, totalTime time.Duration) {
+func printSummary(report scanner.ChainReport, topN int, totalTime time.Duration, domain string) {
 	w := os.Stderr
 
 	fmt.Fprintf(w, "\n")
@@ -295,6 +332,7 @@ func printSummary(report scanner.ChainReport, topN int, totalTime time.Duration)
 				break // Only show hint for the first failing step
 			}
 		}
+		fmt.Fprintf(w, "\n  %sSee full guide: https://github.com/SamNet-dev/findns/blob/main/GUIDE.md%s\n", colorDim, colorReset)
 		fmt.Fprintln(w)
 		return
 	}
@@ -346,6 +384,28 @@ func printSummary(report scanner.ChainReport, topN int, totalTime time.Duration)
 		fmt.Fprintf(w, "  %s... and %d more in %s%s\n", colorDim, len(report.Passed)-limit, outputFile, colorReset)
 	}
 
+	// Next steps guidance
+	fmt.Fprintf(w, "\n  %sNext steps:%s\n", colorBold, colorReset)
+	fmt.Fprintf(w, "    %s\u2022%s Results saved to %s%s%s\n", colorDim, colorReset, colorCyan, outputFile, colorReset)
+	if domain != "" && len(report.Passed) > 0 {
+		topIP := report.Passed[0].IP
+		fmt.Fprintf(w, "    %s\u2022%s Test top resolver: %snslookup %s %s%s\n",
+			colorDim, colorReset, colorDim, domain, topIP, colorReset)
+	}
+	// Check if e2e was in pipeline
+	hasE2E := false
+	hasTunnel := false
+	for _, s := range report.Steps {
+		if strings.Contains(s.Name, "e2e") {
+			hasE2E = true
+		}
+		if strings.Contains(s.Name, "tunnel") {
+			hasTunnel = true
+		}
+	}
+	if hasTunnel && !hasE2E && len(report.Passed) > 0 {
+		fmt.Fprintf(w, "    %s\u2022%s Run with --pubkey to test full tunnel connectivity (e2e)\n", colorDim, colorReset)
+	}
 	fmt.Fprintln(w)
 }