lockpicks 0.3.0 → 0.4.0

package/dist/lockpick.mjs

@@ -6683,8 +6683,8 @@ var require_formats = __commonJS({
         return false;
       const year = +matches[1];
       const month = +matches[2];
-      const day = +matches[3];
-      return month >= 1 && month <= 12 && day >= 1 && day <= (month === 2 && isLeapYear(year) ? 29 : DAYS[month]);
+      const day2 = +matches[3];
+      return month >= 1 && month <= 12 && day2 >= 1 && day2 <= (month === 2 && isLeapYear(year) ? 29 : DAYS[month]);
     }
     function compareDate(d1, d2) {
       if (!(d1 && d2))
@@ -7386,7 +7386,8 @@ function _getBuiltinFlags(long, short, userNames, userAliases) {
 
 // src/commands.ts
 import { randomUUID as randomUUID6 } from "node:crypto";
-import { readFile as readFile5, writeFile as writeFile2 } from "node:fs/promises";
+import { access as access2, mkdir as mkdir4, readFile as readFile5, writeFile as writeFile2 } from "node:fs/promises";
+import { dirname as dirname5 } from "node:path";
 import { hostname as hostname3 } from "node:os";
 
 // ../../node_modules/.pnpm/@modelcontextprotocol+sdk@1.30.1_zod@4.4.3/node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
@@ -11497,12 +11498,12 @@ var $ZodPipe = /* @__PURE__ */ $constructor("$ZodPipe", (inst, def) => {
     return handlePipeResult(left, def.out, ctx);
   };
 });
-function handlePipeResult(left, next, ctx) {
+function handlePipeResult(left, next2, ctx) {
   if (left.issues.length) {
     left.aborted = true;
     return left;
   }
-  return next._zod.run({ value: left.value, issues: left.issues, fallback: left.fallback }, ctx);
+  return next2._zod.run({ value: left.value, issues: left.issues, fallback: left.fallback }, ctx);
 }
 var $ZodCodec = /* @__PURE__ */ $constructor("$ZodCodec", (inst, def) => {
   $ZodType.init(inst, def);
@@ -23580,6 +23581,74 @@ function readBriefCommand(agent2, file2 = FIX_ALL_FILE) {
   );
 }
 
+// ../../packages/contracts/src/run-outcome.ts
+var RUN_OUTCOME_LEVELS = [
+  "full",
+  "headers-only",
+  "blocked",
+  "transport",
+  "unreachable",
+  "terminal-failure"
+];
+var runOutcomeLevelSchema = external_exports.enum(RUN_OUTCOME_LEVELS);
+var RUN_OUTCOME_COVERAGE = [
+  "page",
+  "headers-and-records",
+  "records-only",
+  "none"
+];
+var runOutcomeCoverageSchema = external_exports.enum(RUN_OUTCOME_COVERAGE);
+var RUN_CHALLENGE_VENDORS = ["cloudflare", "vercel", "other"];
+var runChallengeVendorSchema = external_exports.enum(RUN_CHALLENGE_VENDORS);
+var RUN_OUTCOME_REASONS = [
+  "no-address",
+  "dns-error",
+  "private-address",
+  "refused",
+  "no-answer",
+  "connection-closed",
+  "certificate",
+  "old-tls",
+  "large-headers",
+  "invalid-response",
+  "www",
+  "other-site",
+  "sign-in",
+  "redirect-loop",
+  "redirect",
+  "bot-check",
+  "denied",
+  "rate-limited",
+  "not-found",
+  "gone",
+  "client-error",
+  "server-error",
+  "maintenance",
+  "parked",
+  "empty",
+  "not-html",
+  "app-shell",
+  "interrupted",
+  "not-delivered"
+];
+var runOutcomeReasonSchema = external_exports.enum(RUN_OUTCOME_REASONS);
+var publicRunOutcomeSchema = external_exports.object({
+  level: runOutcomeLevelSchema,
+  coverage: runOutcomeCoverageSchema,
+  reason: runOutcomeReasonSchema.optional(),
+  vendor: runChallengeVendorSchema.optional(),
+  /** HTTP status the homepage answered with, when one arrived. */
+  homepageStatus: external_exports.number().int().min(100).max(599).optional(),
+  /** Where a www-twin or cross-site redirect pointed, to check instead. */
+  redirectOrigin: external_exports.string().max(300).optional(),
+  /**
+   * Terminal failures only: whether the run had contacted the site before it
+   * stopped. A run is charged at its first contact, so false also means it
+   * did not use one of the account's runs.
+   */
+  contacted: external_exports.boolean().optional()
+});
+
 // ../../packages/contracts/src/quick-check.ts
 var QUICK_CHECK_IDS = [
   "https",
@@ -23640,6 +23709,7 @@ var QUICK_STACK = [
 ];
 var quickStackSchema = external_exports.enum(QUICK_STACK);
 var QUICK_STACK_MAX = 8;
+var PULSE_STACK_MAX = 12;
 var QUICK_CHECK_MAX_REQUESTS = 6;
 var quickCheckFailureSchema = external_exports.enum([
   "unreachable",
@@ -23649,7 +23719,9 @@ var quickCheckFailureSchema = external_exports.enum([
   "unsupported-response",
   "timeout",
   "budget",
-  "unavailable"
+  "unavailable",
+  /** A bot check answered instead of the homepage (any status, 200 included). */
+  "bot-check"
 ]);
 var severitySchema = external_exports.enum(["high", "medium", "low", "info"]);
 var statusSchema = external_exports.enum(["pass", "attention", "unknown"]);
@@ -23664,6 +23736,8 @@ var quickCheckSummarySchema = external_exports.object({
   outcome: external_exports.enum(["complete", "partial", "failed"]),
   failure: quickCheckFailureSchema.optional(),
   httpStatus: external_exports.int().min(100).max(599).optional(),
+  /** With `bot-check`: whose bot check answered. */
+  challengeVendor: runChallengeVendorSchema.optional(),
   redirectOrigin: external_exports.url().max(300).optional(),
   /** The www twin the homepage redirected to; the checks describe it. */
   finalOrigin: external_exports.url().max(300).optional(),
@@ -23701,6 +23775,8 @@ var quickCheckTldrSchema = external_exports.object({
   status: external_exports.enum(["pending", "complete", "partial", "failed"]),
   failure: quickCheckFailureSchema.optional(),
   httpStatus: external_exports.int().min(100).max(599).optional(),
+  /** With `bot-check`: whose bot check answered. */
+  challengeVendor: runChallengeVendorSchema.optional(),
   redirectOrigin: external_exports.url().max(300).optional(),
   worthFixing: external_exports.int().nonnegative(),
   notes: external_exports.int().nonnegative(),
@@ -23736,6 +23812,25 @@ var quickCheckTldrSchema = external_exports.object({
   expiresAt: external_exports.iso.datetime()
 }).strict();
 
+// ../../packages/contracts/src/scan-standards.ts
+var standardsReferenceSchema = external_exports.object({
+  owasp: external_exports.array(external_exports.string().regex(/^A(?:0[1-9]|10):2025$/)).max(10),
+  cwe: external_exports.array(external_exports.string().regex(/^CWE-\d+$/)).max(20),
+  asvs: external_exports.array(external_exports.string().regex(/^v5\.0\.0-\d+\.\d+\.\d+$/)).max(20),
+  wstg: external_exports.array(external_exports.string().regex(/^WSTG-v42-[A-Z]+-\d+$/)).max(20),
+  relationship: external_exports.literal("related-control")
+}).strict();
+var standardsSummarySchema = external_exports.object({
+  wstgVersion: external_exports.literal("4.2"),
+  owaspVersion: external_exports.literal("2025"),
+  asvsVersion: external_exports.literal("5.0.0"),
+  mappingVersion: external_exports.literal("1"),
+  levelOneRequirements: external_exports.number().int().nonnegative(),
+  relatedLevelOneRequirements: external_exports.number().int().nonnegative(),
+  verifiedLevelOneRequirements: external_exports.literal(0),
+  unverifiedLevelOneRequirements: external_exports.number().int().nonnegative()
+}).strict();
+
 // ../../packages/contracts/src/finding-triage.ts
 var FINDING_VERDICTS = [
   "confirmed",
@@ -23774,6 +23869,510 @@ var findingTriageSchema = external_exports.object({
   message: "A not_actionable verdict needs positive defeating evidence."
 });
 
+// ../../packages/contracts/src/public-pulse.ts
+var explanationSchema = external_exports.object({
+  title: external_exports.string(),
+  meaning: external_exports.string(),
+  fix: external_exports.string()
+});
+var evidenceClassSchema = external_exports.enum([
+  "observed",
+  "suspected",
+  "informational"
+]);
+var publicCoverageAreaSchema = external_exports.enum([
+  "html",
+  "scripts",
+  "maps",
+  "exposure",
+  "cors",
+  "tls",
+  "validation",
+  "components",
+  "security-policy",
+  "domain",
+  "sitemap"
+]);
+var assessmentEvidenceSchema = external_exports.object({
+  version: external_exports.literal("assessment-evidence@1"),
+  observations: external_exports.number().int().nonnegative(),
+  suspected: external_exports.number().int().nonnegative(),
+  informational: external_exports.number().int().nonnegative(),
+  unassessedChecks: external_exports.number().int().nonnegative(),
+  areas: external_exports.array(
+    external_exports.object({
+      area: publicCoverageAreaSchema,
+      state: external_exports.enum(["complete", "limited", "not-run", "unknown"]),
+      reason: external_exports.enum([
+        "sampled",
+        "incomplete",
+        "not-assessed",
+        "historical-unavailable"
+      ])
+    })
+  )
+});
+var publicCheckSchema = external_exports.object({
+  standards: standardsReferenceSchema.optional(),
+  id: external_exports.string(),
+  category: external_exports.string(),
+  status: external_exports.enum(["pass", "attention", "unknown"]),
+  severity: external_exports.enum(["medium", "low", "info"]),
+  plain: explanationSchema,
+  technical: explanationSchema,
+  evidence: external_exports.string(),
+  affected: external_exports.array(external_exports.string()),
+  prompt: external_exports.string(),
+  triage: findingTriageSchema.optional()
+});
+var publicFindingSchema = external_exports.object({
+  standards: standardsReferenceSchema.optional(),
+  id: external_exports.string(),
+  kind: external_exports.string(),
+  severity: external_exports.enum(["high", "medium", "low", "info"]),
+  confidence: external_exports.enum(["observed", "potential"]),
+  evidenceClass: evidenceClassSchema.optional(),
+  sources: external_exports.array(external_exports.string()),
+  evidence: external_exports.string(),
+  plain: explanationSchema,
+  technical: explanationSchema,
+  prompt: external_exports.string(),
+  validation: external_exports.object({
+    status: external_exports.enum([
+      "repeatable",
+      "not-reproduced",
+      "inconclusive",
+      "not-tested"
+    ]),
+    detail: external_exports.string()
+  }).optional(),
+  triage: findingTriageSchema.optional()
+});
+var PULSE_BOOKING_SERVICES = [
+  "calendly",
+  "cal-com",
+  "savvycal",
+  "acuity",
+  "hubspot-meetings",
+  "zoom",
+  "stripe-payment-link"
+];
+var PULSE_COMMUNITY_SERVICES = ["skool"];
+var PULSE_VISITOR_DATA_SERVICES = [
+  "amplitude",
+  "google-analytics",
+  "hotjar",
+  "mixpanel",
+  "posthog",
+  "segment",
+  "sentry"
+];
+var PULSE_DNS_HOSTS = [
+  "wix",
+  "cloudflare",
+  "godaddy",
+  "namecheap",
+  "route53",
+  "squarespace",
+  "google-cloud-dns",
+  "vercel",
+  "netlify",
+  "hostinger",
+  "ionos",
+  "porkbun",
+  "dnsimple"
+];
+var PULSE_MAIL_PROVIDERS = [
+  "google-workspace",
+  "microsoft-365",
+  "zoho",
+  "proton",
+  "fastmail"
+];
+var PULSE_EMAIL_SENDERS = [
+  "google-workspace",
+  "microsoft-365",
+  "sendgrid",
+  "mailgun",
+  "amazon-ses",
+  "postmark",
+  "mailchimp",
+  "hubspot",
+  "salesforce",
+  "zendesk",
+  "resend"
+];
+var PULSE_CHAIN_IDS = ["impersonation", "borrowed-address"];
+var day = external_exports.string().regex(/^\d{4}-\d{2}-\d{2}$/);
+var attackChainSchema = external_exports.object({
+  id: external_exports.enum(PULSE_CHAIN_IDS),
+  severity: external_exports.literal("high"),
+  confidence: external_exports.enum(["observed", "potential"]),
+  /** Evidence ids: finding ids, or `contact-surface:*`, `email-policy:*`, `configuration:*`. */
+  ingredients: external_exports.array(external_exports.string()),
+  strengtheners: external_exports.array(external_exports.string())
+});
+var certificateRetrievalSchema = external_exports.object({
+  mode: external_exports.enum(["live", "shared-cache", "memory-cache"]),
+  retrievedAt: external_exports.iso.datetime().optional(),
+  expiresAt: external_exports.iso.datetime().optional()
+}).strict();
+var domainMapSchema = external_exports.object({
+  domain: external_exports.string(),
+  /** `crtsh-sql` is crt.sh's database; `certspotter` covers current certificates only. */
+  source: external_exports.enum(["crt.sh", "crtsh-sql", "certspotter"]),
+  retrieval: certificateRetrievalSchema.optional(),
+  names: external_exports.array(
+    external_exports.object({
+      name: external_exports.string(),
+      controller: external_exports.enum(["you", "third-party", "nobody"]).optional(),
+      chain: external_exports.array(external_exports.string()),
+      firstSeen: day,
+      lastIssued: day,
+      lastExpiry: day
+    })
+  )
+});
+var targetRegistrationSchema = external_exports.discriminatedUnion("state", [
+  external_exports.object({
+    state: external_exports.literal("available"),
+    domain: external_exports.string().min(1).max(253),
+    expiresAt: external_exports.iso.date().optional(),
+    statuses: external_exports.array(external_exports.string().max(128)).max(128)
+  }).strict(),
+  external_exports.object({
+    state: external_exports.enum([
+      "not-found",
+      "unsupported",
+      "unavailable",
+      "not-configured"
+    ]),
+    domain: external_exports.string().min(1).max(253)
+  }).strict(),
+  external_exports.object({ state: external_exports.literal("not-applicable") }).strict()
+]);
+var publicRecordsSchema = external_exports.object({
+  readAt: external_exports.string(),
+  certificateHistory: external_exports.enum(["available", "unavailable", "not-configured"]),
+  policyQueries: external_exports.number().int().nonnegative(),
+  sweepQueries: external_exports.number().int().nonnegative(),
+  spfQueries: external_exports.number().int().nonnegative(),
+  rdapLookups: external_exports.number().int().nonnegative(),
+  targetRegistrationLookups: external_exports.number().int().min(0).max(1).optional(),
+  targetRegistration: targetRegistrationSchema.optional(),
+  /** DS presence queries over DNS-over-HTTPS; absent when not configured. */
+  dnssecQueries: external_exports.number().int().nonnegative().optional()
+});
+var contactSurfaceSchema = external_exports.object({
+  emails: external_exports.number().int().nonnegative(),
+  onDomainEmails: external_exports.array(external_exports.string()),
+  phones: external_exports.number().int().nonnegative(),
+  booking: external_exports.array(external_exports.enum(PULSE_BOOKING_SERVICES)),
+  community: external_exports.array(external_exports.enum(PULSE_COMMUNITY_SERVICES))
+});
+var providersSchema = external_exports.object({
+  dns: external_exports.enum(PULSE_DNS_HOSTS).optional(),
+  mail: external_exports.enum(PULSE_MAIL_PROVIDERS).optional(),
+  senders: external_exports.array(external_exports.enum(PULSE_EMAIL_SENDERS))
+});
+var apiAccessClassificationSchema = external_exports.enum([
+  "protected",
+  "open-data",
+  "open-sensitive",
+  "open-metadata",
+  "error-disclosure",
+  "auth-mismatch",
+  "absent"
+]);
+var baasValueClassificationSchema = external_exports.enum([
+  "protected",
+  "open-data",
+  "open-sensitive",
+  "open-metadata",
+  "error-disclosure",
+  "auth-mismatch",
+  "absent",
+  "inconclusive"
+]);
+var apiSurfaceSchema = external_exports.object({
+  counts: external_exports.object({
+    mapped: external_exports.number().int().nonnegative(),
+    protected: external_exports.number().int().nonnegative(),
+    open: external_exports.number().int().nonnegative(),
+    notChecked: external_exports.number().int().nonnegative(),
+    absent: external_exports.number().int().nonnegative()
+  }),
+  /** The endpoints that answered with data to an unauthenticated GET. */
+  open: external_exports.array(
+    external_exports.object({
+      method: external_exports.enum(["GET", "HEAD"]),
+      path: external_exports.string(),
+      status: external_exports.number().int().min(0).max(599),
+      contentType: external_exports.string(),
+      classification: apiAccessClassificationSchema,
+      /** Top-level field names only, never their values. */
+      fields: external_exports.array(external_exports.string()).max(20).optional(),
+      records: external_exports.number().int().nonnegative().optional()
+    })
+  ).max(50),
+  graphql: external_exports.object({
+    endpoint: external_exports.string(),
+    introspection: external_exports.enum(["enabled", "not-checked"]),
+    queries: external_exports.number().int().nonnegative().optional(),
+    mutations: external_exports.number().int().nonnegative().optional()
+  }).optional(),
+  /**
+   * Anonymous reads of the NextAuth/Auth.js and Better Auth session routes
+   * (engine 2.13). Absent routes are dropped; field names only, never values.
+   */
+  authSessions: external_exports.array(
+    external_exports.object({
+      path: external_exports.string(),
+      library: external_exports.enum(["authjs", "better-auth"]),
+      status: external_exports.number().int().min(0).max(599),
+      classification: external_exports.enum(["protected", "anonymous", "session-exposed"]),
+      sharedCacheable: external_exports.boolean().optional(),
+      fields: external_exports.array(external_exports.string()).max(20).optional()
+    })
+  ).max(2).optional(),
+  /**
+   * Managed-backend follow-through (engine 2.14): Supabase REST tables and
+   * Firebase realtime databases the anon key or a public read could answer.
+   * Table and key names only, never values.
+   */
+  baas: external_exports.object({
+    supabase: external_exports.array(
+      external_exports.object({
+        url: external_exports.string(),
+        tables: external_exports.array(
+          external_exports.object({
+            table: external_exports.string(),
+            status: external_exports.number().int().min(0).max(599),
+            classification: baasValueClassificationSchema,
+            /** Declared column names only, never their values. */
+            fields: external_exports.array(external_exports.string()).max(20).optional(),
+            /** Top-level field count when no declared name is published. */
+            fieldCount: external_exports.number().int().nonnegative().optional(),
+            records: external_exports.number().int().nonnegative().optional()
+          })
+        ).max(5),
+        unprobed: external_exports.number().int().nonnegative().optional()
+      })
+    ).max(1).optional(),
+    firebase: external_exports.array(
+      external_exports.object({
+        url: external_exports.string(),
+        status: external_exports.number().int().min(0).max(599),
+        classification: external_exports.enum(["public", "protected", "absent"]),
+        /** Top-level key count only; a key can itself be customer data. */
+        keyCount: external_exports.number().int().nonnegative().optional()
+      })
+    ).max(1).optional(),
+    convex: external_exports.array(
+      external_exports.object({
+        url: external_exports.string(),
+        functions: external_exports.array(
+          external_exports.object({
+            path: external_exports.string(),
+            status: external_exports.number().int().min(0).max(599),
+            classification: apiAccessClassificationSchema,
+            /** Field count only; a value can be keyed by customer data. */
+            fieldCount: external_exports.number().int().nonnegative().optional(),
+            records: external_exports.number().int().nonnegative().optional()
+          })
+        ).max(5),
+        unprobed: external_exports.number().int().nonnegative().optional()
+      })
+    ).max(1).optional()
+  }).optional(),
+  /**
+   * Deep's coverage ledger (C2): every investigation packet closed as found,
+   * not found, not applicable or could not check, with a reason. This is the
+   * customer-visible "what we checked", made systematic. It carries no prompt,
+   * tool choice or ordering detail, only the packet, its impact, the outcome,
+   * a coded reason and the counts.
+   */
+  coverageLedger: external_exports.object({
+    version: external_exports.literal("1"),
+    entries: external_exports.array(
+      external_exports.object({
+        packet: external_exports.enum([
+          "supabase-rls",
+          "storage-buckets",
+          "script-routes",
+          "auth-endpoints"
+        ]),
+        impact: external_exports.enum([
+          "data-exposure",
+          "auth-surface",
+          "exposed-files",
+          "configuration"
+        ]),
+        outcome: external_exports.enum([
+          "found",
+          "not-found",
+          "not-applicable",
+          "could-not-check"
+        ]),
+        reason: external_exports.string(),
+        requests: external_exports.number().int().nonnegative(),
+        budget: external_exports.number().int().nonnegative(),
+        findings: external_exports.number().int().nonnegative().optional(),
+        references: external_exports.number().int().nonnegative().optional()
+      })
+    ).max(20)
+  }).optional(),
+  truncated: external_exports.number().int().nonnegative().optional()
+});
+var SOURCE_MAP_BASELINES = [
+  "published",
+  "none",
+  "not-checked"
+];
+var sourceMapBaselineSchema = external_exports.enum(SOURCE_MAP_BASELINES);
+var EXPOSURE_CHECK_STATES = [
+  "clear",
+  "found",
+  "not-run",
+  "could-not-run"
+];
+var EXPOSURE_CHECK_LIMITS = [
+  "no-source-map",
+  "source-map-unread",
+  "budget"
+];
+var exposureCheckSchema = external_exports.object({
+  state: external_exports.enum(EXPOSURE_CHECK_STATES),
+  /** Empty when discovery ran at full confidence. */
+  limits: external_exports.array(external_exports.enum(EXPOSURE_CHECK_LIMITS)).max(3),
+  sourceMap: sourceMapBaselineSchema
+});
+function exposureCheckHeadline(check3) {
+  return check3.state === "clear" && check3.limits.length ? "clear-limited" : check3.state;
+}
+var EXPOSURE_CHECK_TEXT = {
+  title: {
+    clear: "No unintended public API routes or pages found exposed.",
+    "clear-limited": "No exposed API routes or pages found, but coverage was limited, so this is not a full all-clear.",
+    found: "Deep found API routes or pages that answer without sign-in.",
+    "not-run": "This run did not check for exposed API routes and pages.",
+    "could-not-run": "Deep could not finish checking for exposed API routes and pages, so this report makes no claim about them."
+  },
+  limits: {
+    "no-source-map": "Your site publishes no source maps, so Deep had fewer routes and pages to find.",
+    "source-map-unread": "Deep did not read your source maps on this run, so it had fewer routes and pages to find.",
+    budget: "Deep reached its request limit before it finished looking."
+  }
+};
+function exposureCheckLines(check3) {
+  return [
+    EXPOSURE_CHECK_TEXT.title[exposureCheckHeadline(check3)],
+    ...check3.state === "clear" ? check3.limits.map((limit) => EXPOSURE_CHECK_TEXT.limits[limit]) : []
+  ];
+}
+var publicPulseReportSchema = external_exports.object({
+  schemaVersion: external_exports.literal("public-pulse@1"),
+  assessment: assessmentEvidenceSchema.optional(),
+  standards: standardsSummarySchema.optional(),
+  target: external_exports.object({
+    shape: external_exports.enum(["html", "client-rendered", "api", "document"]),
+    signals: external_exports.array(
+      external_exports.enum([
+        "structured-json",
+        "html-response",
+        "small-html",
+        "empty-root",
+        "script-reference",
+        "few-links"
+      ])
+    ).max(6).optional(),
+    rendering: external_exports.enum([
+      "not-requested",
+      "complete",
+      "limited",
+      "unavailable"
+    ]),
+    blockedRequests: external_exports.number().int().nonnegative(),
+    observedCookies: external_exports.number().int().nonnegative().optional(),
+    secureCookies: external_exports.number().int().nonnegative().optional(),
+    httpOnlyCookies: external_exports.number().int().nonnegative().optional(),
+    /** Built-with chips, shared stack vocabulary. Not a finding. */
+    stack: external_exports.array(quickStackSchema).max(PULSE_STACK_MAX).optional(),
+    /** Explicit technology and version declarations; never findings. */
+    technologies: external_exports.object({
+      limited: external_exports.boolean(),
+      entries: external_exports.array(
+        external_exports.object({
+          id: quickStackSchema,
+          version: external_exports.string().regex(/^\d{1,3}\.\d{1,3}\.\d{1,3}(?:-[A-Za-z0-9.-]{1,40})?$/).optional(),
+          via: external_exports.enum(["header", "generator", "asset", "code", "banner"])
+        })
+      ).max(24)
+    }).optional(),
+    /**
+     * Companies whose code runs on the page: external and preloaded
+     * scripts by registrable domain. Not a finding.
+     */
+    thirdPartyCode: external_exports.array(
+      external_exports.object({
+        domain: external_exports.string(),
+        stack: quickStackSchema.optional(),
+        integrity: external_exports.enum(["declared", "missing"])
+      })
+    ).optional(),
+    /**
+     * Companies the page sends visitor activity to, from known endpoints
+     * in its own script text. Never companies that run code. Not a finding.
+     */
+    thirdPartyData: external_exports.array(
+      external_exports.object({
+        service: external_exports.enum(PULSE_VISITOR_DATA_SERVICES),
+        hosts: external_exports.array(external_exports.string())
+      })
+    ).optional(),
+    /** Owner only. */
+    contactSurface: contactSurfaceSchema.optional(),
+    /** Owner only. */
+    providers: providersSchema.optional()
+  }).optional(),
+  methodology: external_exports.literal("public-surface"),
+  methodologyVersion: external_exports.literal("1"),
+  checks: external_exports.array(publicCheckSchema),
+  surface: external_exports.object({
+    findings: external_exports.array(publicFindingSchema),
+    chains: external_exports.array(attackChainSchema).optional(),
+    /** Deep only. Counts and the endpoints that answered without sign-in. */
+    apiSurface: apiSurfaceSchema.optional(),
+    /** Owner only. */
+    domainMap: domainMapSchema.optional(),
+    /** Owner only. When public records were read and what that cost. */
+    publicRecords: publicRecordsSchema.optional()
+  }).optional(),
+  score: external_exports.number().min(0).max(100).nullable(),
+  coverage: external_exports.number().min(0).max(100),
+  pages: external_exports.number().int().nonnegative(),
+  requests: external_exports.number().int().nonnegative(),
+  limitations: external_exports.array(external_exports.string()),
+  stoppedReason: external_exports.string().optional(),
+  /**
+   * Deep only, and present even when the run stopped before its surface
+   * stage: whether unintended public API routes and pages were found.
+   */
+  exposureCheck: exposureCheckSchema.optional(),
+  /** How far collection got (engine 2.18+; derived for older reports). */
+  outcome: publicRunOutcomeSchema.optional()
+});
+var publicPulseChangeSchema = external_exports.object({
+  id: external_exports.string(),
+  kind: external_exports.enum(["new", "persistent", "absent", "unknown"]),
+  area: external_exports.enum(["configuration", "exposure"]),
+  title: external_exports.string(),
+  severity: external_exports.string(),
+  explanation: external_exports.string(),
+  /** What the recheck proves about an earlier finding; absent for a new one. */
+  outcome: recheckStatusSchema.optional()
+});
+
 // ../../packages/contracts/src/cli-routes.ts
 var CLI_API = "/api/cli/v1";
 var segment = (value) => encodeURIComponent(value);
@@ -23786,6 +24385,8 @@ var CLI_API_ROUTES = {
   projectStatus: (projectId) => `${CLI_API}/projects/${segment(projectId)}/status`,
   /** POST: start a Pulse (needs the `pulse` scope). */
   projectPulse: (projectId) => `${CLI_API}/projects/${segment(projectId)}/pulse`,
+  /** POST: start a release's Deep scan (a CI key with the `deep` scope). */
+  projectDeep: (projectId) => `${CLI_API}/projects/${segment(projectId)}/deep`,
   runs: `${CLI_API}/runs`,
   run: (runId) => `${CLI_API}/runs/${segment(runId)}`,
   findings: (runId) => `${CLI_API}/runs/${segment(runId)}/findings`,
@@ -23978,7 +24579,18 @@ var cliRunDetailSchema = cliRunSummarySchema.extend({
     percent: external_exports.number().nullable(),
     limitations: external_exports.array(external_exports.string())
   }),
-  caveats: external_exports.array(external_exports.string())
+  caveats: external_exports.array(external_exports.string()),
+  /**
+   * Pulse, Standard and Deep: how far collection got (blocked, unreachable
+   * and so on) and what the report is based on. Null for pentests and
+   * unfinished runs.
+   */
+  outcome: publicRunOutcomeSchema.nullable().optional(),
+  /**
+   * Deep only: whether unintended public API routes and pages were found,
+   * as a state and coded limits. Never the routes requested. Null otherwise.
+   */
+  exposureCheck: exposureCheckSchema.nullable().optional()
 });
 var CLI_FINDING_STATES = [
   "attention",
@@ -24212,7 +24824,18 @@ var agentScanSchema = external_exports.strictObject({
     percent: external_exports.number().nullable(),
     limitations: external_exports.array(external_exports.string())
   }),
-  caveats: external_exports.array(external_exports.string())
+  caveats: external_exports.array(external_exports.string()),
+  /**
+   * How far collection got and what the report is based on. Only a `full`
+   * run is ever graded; the others say why (a bot check, no DNS address).
+   * Null for pentests and unfinished runs.
+   */
+  outcome: publicRunOutcomeSchema.nullable(),
+  /**
+   * Deep only: whether unintended public API routes and pages were found.
+   * Absent for Pulse, Standard and pentests, and from older servers.
+   */
+  exposureCheck: exposureCheckSchema.optional()
 });
 var agentSiteSchema = external_exports.strictObject({
   id: agentIdSchema,
@@ -24909,14 +25532,53 @@ async function readLockfiles(dir) {
   return { packages, sources, skipped };
 }
 
+// src/terminal.ts
+var UNSAFE = /[\u0000-\u0008\u000b-\u001f\u007f-\u009f؜‎‏‪-‮⁦-⁩]/g;
+function neutralize(text2) {
+  return text2.replace(/\r\n/g, "\n").replace(UNSAFE, (char) => {
+    const code = char.charCodeAt(0);
+    if (code < 32) return String.fromCharCode(9216 + code);
+    if (code === 127) return "\u2421";
+    return "\uFFFD";
+  });
+}
+function neutralizeDeep(value) {
+  if (typeof value === "string") return neutralize(value);
+  if (Array.isArray(value)) return value.map(neutralizeDeep);
+  if (value && typeof value === "object") {
+    const copy = {};
+    for (const [key, child] of Object.entries(value))
+      copy[key] = neutralizeDeep(child);
+    return copy;
+  }
+  return value;
+}
+var OWN_STYLE = /\u001b\[(?:1|2|22|31|32|33|36|39)m/g;
+function terminalSafe(text2) {
+  const styles = text2.match(OWN_STYLE) ?? [];
+  return text2.split(OWN_STYLE).map((part, index) => neutralize(part) + (styles[index] ?? "")).join("");
+}
+function terminalWidth(stream) {
+  return stream.isTTY && stream.columns ? stream.columns : null;
+}
+
 // src/api.ts
 function friendlyError(status2, message, replace) {
   if (status2 === 404 && message === "Not found" && replace.notFound)
     return replace.notFound;
+  const permission = status2 === 403 && message?.match(/^Missing required permission: (\S+)$/);
+  if (permission)
+    return PERMISSION_TEXT[permission[1]] ?? `Your role does not allow this (it needs ${permission[1]}).`;
   if (status2 === 403 && message === "This CLI key does not have the required scope" && replace.forbidden)
     return replace.forbidden;
   return message ?? null;
 }
+var PERMISSION_TEXT = {
+  "audit.launch": "Your role on this site lets you read results, not start scans. Ask a project manager for the contributor role.",
+  "project.read": "You do not have access to this site.",
+  "report.read": "You do not have access to this site's results.",
+  "project.manage": "Only a project manager or workspace admin can change this site."
+};
 var missingRun = (runId) => `No run "${runId}" in this workspace.`;
 var LockpickApiError = class extends Error {
   constructor(message, status2, code, agentError = null) {
@@ -24991,10 +25653,10 @@ function mappedLocalIPv4(name) {
   return localIPv4([high >> 8, high & 255, low >> 8, low & 255]);
 }
 function normalizeHost(value) {
-  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(value) ? value : `http://${value}`;
+  const explicit = /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
   let url3;
   try {
-    url3 = new URL(withScheme);
+    url3 = new URL(explicit ? value : `http://${value}`);
   } catch {
     throw new LockpickApiError(
       "Invalid Lockpick host URL.",
@@ -25002,9 +25664,8 @@ function normalizeHost(value) {
       "VALIDATION_ERROR"
     );
   }
-  const name = url3.hostname.toLowerCase().replace(/^\[|\]$/g, "");
-  const ipKind = isIP(name);
-  const local = name === "localhost" || name === "::1" || ipKind === 6 && (/^f[cd]/.test(name) || mappedLocalIPv4(name)) || ipKind === 4 && localIPv4(name.split(".").map(Number)) || ipKind === 0 && (!name.includes(".") || name.endsWith(".local") || name.endsWith(".ts.net"));
+  if (!explicit && !localHostname(url3.hostname)) url3.protocol = "https:";
+  const local = localHostname(url3.hostname);
   if (url3.protocol !== "https:" && !(url3.protocol === "http:" && local) || url3.username || url3.password || url3.search || url3.hash)
     throw new LockpickApiError(
       "Use an HTTPS Lockpick host, or HTTP on a local network; omit credentials, query and fragment.",
@@ -25013,6 +25674,37 @@ function normalizeHost(value) {
     );
   return url3.origin;
 }
+function localHostname(hostname4) {
+  const name = hostname4.toLowerCase().replace(/^\[|\]$/g, "");
+  const ipKind = isIP(name);
+  return name === "localhost" || name === "::1" || ipKind === 6 && (/^f[cd]/.test(name) || mappedLocalIPv4(name)) || ipKind === 4 && localIPv4(name.split(".").map(Number)) || ipKind === 0 && (!name.includes(".") || name.endsWith(".local") || name.endsWith(".ts.net"));
+}
+var HostRedirectError = class extends LockpickApiError {
+  constructor(host, canonicalHost, status2) {
+    super(
+      canonicalHost ? `${host} redirects to ${canonicalHost}. Use \`--host ${canonicalHost}\`.` : `${host} redirected the request elsewhere. Check the Lockpick host.`,
+      status2,
+      "HOST_REDIRECT"
+    );
+    this.host = host;
+    this.canonicalHost = canonicalHost;
+  }
+  host;
+  canonicalHost;
+};
+function hostRedirect(host, requested, response) {
+  if (response.status < 300 || response.status > 399) return null;
+  let canonical = null;
+  try {
+    const target = new URL(response.headers.get("location") ?? "", requested);
+    const origin = normalizeHost(target.origin);
+    if (origin !== host && target.pathname === requested.pathname)
+      canonical = origin;
+  } catch {
+    canonical = null;
+  }
+  return new HostRedirectError(host, canonical, response.status);
+}
 var pageQuery = (query) => Object.fromEntries(
   Object.entries(query).filter(([, value]) => value !== void 0 && value !== false).map(([name, value]) => [name, String(value)])
 );
@@ -25025,8 +25717,14 @@ var LockpickClient = class {
   host;
   key;
   fetchImpl;
+  /**
+   * Server text as the CLI may show it: the key never appears, and terminal
+   * control characters are neutralized (`terminal.ts`).
+   */
   redact(text2) {
-    return this.key ? text2.replaceAll(this.key, "[redacted]") : text2;
+    return neutralize(
+      this.key ? text2.replaceAll(this.key, "[redacted]") : text2
+    );
   }
   redactAgent(error51) {
     return {
@@ -25095,7 +25793,8 @@ var LockpickClient = class {
           method: init.method ?? "GET",
           headers,
           body: init.body === void 0 ? void 0 : JSON.stringify(init.body),
-          redirect: "error",
+          // Never followed (the key must not travel); see `hostRedirect`.
+          redirect: "manual",
           signal: controller.signal
         }),
         deadline
@@ -25121,6 +25820,8 @@ var LockpickClient = class {
     } finally {
       clearTimeout(timeout);
     }
+    const redirect = hostRedirect(this.host, url3, response);
+    if (redirect) throw redirect;
     if (!envelope || typeof envelope !== "object" || !("data" in envelope))
       throw new LockpickApiError(
         `${this.host} did not answer as Lockpick (HTTP ${response.status}). Check the URL, and that CLI access is enabled there.`,
@@ -25143,7 +25844,7 @@ var LockpickClient = class {
         response.status,
         "CONTRACT_MISMATCH"
       );
-    return parsed.data;
+    return neutralizeDeep(parsed.data);
   }
   startDeviceLogin(client) {
     return this.request(
@@ -25627,6 +26328,11 @@ async function clientFor(options = {}) {
 }
 
 // src/doctor.ts
+var CAPABILITY_GAP = {
+  pulse: "your role on every site here only lets you read results.",
+  sites: "your workspace role cannot add sites.",
+  deep: "Deep is not available to you here (role, early access or server setting)."
+};
 async function runDoctor(options = {}) {
   const checks = [];
   const nodeVersion = options.nodeVersion ?? process.versions.node;
@@ -25672,14 +26378,22 @@ async function runDoctor(options = {}) {
   }
   const fetchImpl = options.fetchImpl ?? fetch;
   try {
-    const response = await fetchImpl(
-      new URL("/api/health/ready", session.host),
-      {
-        method: "GET",
-        redirect: "error",
-        signal: AbortSignal.timeout(1e4)
-      }
-    );
+    const health = new URL("/api/health/ready", session.host);
+    const response = await fetchImpl(health, {
+      method: "GET",
+      redirect: "manual",
+      signal: AbortSignal.timeout(1e4)
+    });
+    const redirect = hostRedirect(session.host, health, response);
+    if (redirect) {
+      checks.push({
+        status: "FAIL",
+        name: "Connection",
+        detail: redirect.message,
+        nextStep: redirect.canonicalHost ? `Run lockpick login --host ${redirect.canonicalHost}.` : "Check the host, then rerun doctor."
+      });
+      return checks;
+    }
     checks.push(
       response.ok ? {
         status: "PASS",
@@ -25718,8 +26432,9 @@ async function runDoctor(options = {}) {
       name: "Authentication",
       detail: `${me.user.name} in ${me.workspace.name} (${me.workspace.id}); key ${me.key.prefix}\u2026`
     });
+    let capabilities = null;
     try {
-      await client.agent.whoami();
+      ({ capabilities } = await client.agent.whoami());
       checks.push({
         status: "PASS",
         name: "Agent API",
@@ -25739,12 +26454,29 @@ async function runDoctor(options = {}) {
         name: "Scope",
         detail: `The key lacks ${options.scope} permission.`,
         nextStep: `Run lockpick login --host ${session.host} --${options.scope} and approve it in the browser.`
+      } : options.scope && capabilities && !capabilities[options.scope] ? {
+        // The key may, but the person's role (or the server) may not:
+        // a project viewer's Pulse key starts nothing.
+        status: "WARN",
+        name: "Scope",
+        detail: `The key has ${options.scope} permission, but ${CAPABILITY_GAP[options.scope]}`,
+        nextStep: "Ask a workspace admin or project manager for the contributor or manager role on a site."
       } : {
         status: "PASS",
         name: "Scope",
         detail: options.scope ? `${options.scope} permission is present.` : `Granted: ${me.key.scopes.join(", ")}.`
       }
     );
+    const daysLeft = Math.floor(
+      (Date.parse(me.key.expiresAt) - Date.now()) / 864e5
+    );
+    if (daysLeft < 7)
+      checks.push({
+        status: "WARN",
+        name: "Key expiry",
+        detail: `The key expires when idle on ${me.key.expiresAt.slice(0, 10)} (${Math.max(0, daysLeft)} days).`,
+        nextStep: "Using it extends it; for CI, sign in again before then."
+      });
   } catch (error51) {
     const apiError = error51 instanceof LockpickApiError ? error51 : null;
     checks.push({
@@ -25766,7 +26498,9 @@ var EXIT = {
   permission: 4,
   validation: 5,
   rateLimit: 6,
-  provider: 7
+  provider: 7,
+  /** A finished scan has open findings at or above `--fail-on`. */
+  findings: 8
 };
 function exitCodeFor(error51) {
   if (!(error51 instanceof LockpickApiError)) return EXIT.error;
@@ -25800,7 +26534,8 @@ var CODES = {
   cyan: [36, 39]
 };
 function painter(stream = process.stdout, env = process.env) {
-  const enabled = Boolean(stream.isTTY) && !env.NO_COLOR && env.TERM !== "dumb";
+  const forced = env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== "0";
+  const enabled = !env.NO_COLOR && env.FORCE_COLOR !== "0" && (forced || Boolean(stream.isTTY) && env.TERM !== "dumb");
   return (style, text2) => {
     if (!enabled) return text2;
     const [open4, close] = CODES[style];
@@ -25830,17 +26565,33 @@ function plural(count, noun) {
 function date5(value) {
   return value ? value.replace("T", " ").slice(0, 16) : "\u2014";
 }
-function table(rows) {
-  const visible = (text2) => text2.replace(/\u001b\[\d+m/g, "").length;
+var STYLE = /\u001b\[\d+m/g;
+var visible = (text2) => text2.replace(STYLE, "").length;
+function clip(text2, max) {
+  if (visible(text2) <= max) return text2;
+  return `${text2.replace(STYLE, "").slice(0, Math.max(1, max - 1))}\u2026`;
+}
+function table(rows, width2, flex = rows[0].length - 1) {
   const widths = rows[0].map(
     (_, column) => Math.max(...rows.map((row) => visible(row[column] ?? "")))
   );
+  if (width2) {
+    const others = widths.reduce(
+      (sum, columnWidth, column) => column === flex ? sum : sum + columnWidth + 2,
+      0
+    );
+    widths[flex] = Math.min(widths[flex], Math.max(16, width2 - others - 1));
+  }
   return rows.map(
-    (row) => row.map(
-      (cell, column) => column === row.length - 1 ? cell : cell + " ".repeat(widths[column] - visible(cell))
-    ).join("  ")
+    (row) => row.map((cell, column) => {
+      const fitted = column === flex ? clip(cell, widths[column]) : cell;
+      return column === row.length - 1 ? fitted : fitted + " ".repeat(Math.max(0, widths[column] - visible(fitted)));
+    }).join("  ")
   ).join("\n");
 }
+function next(paint2, ...commands) {
+  return paint2("dim", `Next: ${commands.join("  \xB7  ")}`);
+}
 function runKindLabel(run2) {
   if (run2.kind === "pentest")
     return run2.mode ? `pentest/${run2.mode}` : "pentest";
@@ -25848,35 +26599,51 @@ function runKindLabel(run2) {
   if (run2.assessmentLevel === "standard") return "Standard";
   return "Pulse";
 }
-function formatErrorLines(message, agentError) {
+function formatErrorLines(message, agentError, docsUrl2) {
   const lines = [message];
   if (agentError?.nextStep) lines.push(agentError.nextStep);
   if (agentError?.retryAfterSeconds !== null && agentError?.retryAfterSeconds !== void 0)
     lines.push(`Retry after ${agentError.retryAfterSeconds} seconds.`);
   if (agentError?.webUrl) lines.push(agentError.webUrl);
+  if (docsUrl2) lines.push(`Help: ${docsUrl2}`);
   return lines;
 }
 function runLine(run2, paint2) {
   if (!run2) return paint2("dim", "none yet");
   return `${statusColor(run2.status, paint2)} ${paint2("dim", `${date5(run2.createdAt)} \xB7 ${run2.id}`)}`;
 }
-function formatProjects(projects2, paint2 = plain) {
+function formatProjects(projects2, paint2 = plain, width2) {
   if (projects2.length === 0)
-    return "No projects you can read in this workspace.";
-  return table([
+    return [
+      "No projects you can read in this workspace.",
+      paint2(
+        "dim",
+        "Add one with `lockpick sites add <url>`, or ask a workspace admin to grant you a project."
+      )
+    ].join("\n");
+  const rows = table(
     [
-      paint2("bold", "PROJECT"),
-      paint2("bold", "ID"),
-      paint2("bold", "PULSE"),
-      paint2("bold", "PENTEST")
+      [
+        paint2("bold", "PROJECT"),
+        paint2("bold", "ID"),
+        paint2("bold", "PULSE"),
+        paint2("bold", "PENTEST")
+      ],
+      ...projects2.map((project) => [
+        project.name,
+        paint2("dim", project.id),
+        project.latestPulse ? statusColor(project.latestPulse.status, paint2) : paint2("dim", "\u2014"),
+        project.latestPentest ? statusColor(project.latestPentest.status, paint2) : paint2("dim", "\u2014")
+      ])
     ],
-    ...projects2.map((project) => [
-      project.name,
-      paint2("dim", project.id),
-      project.latestPulse ? statusColor(project.latestPulse.status, paint2) : paint2("dim", "\u2014"),
-      project.latestPentest ? statusColor(project.latestPentest.status, paint2) : paint2("dim", "\u2014")
-    ])
-  ]);
+    width2,
+    0
+  );
+  return [
+    rows,
+    "",
+    next(paint2, "lockpick status <project>", "lockpick pulse <project>")
+  ].join("\n");
 }
 function runBlock(label, run2, paint2, link) {
   if (!run2) return [`${paint2("bold", label)}  ${paint2("dim", "none yet")}`];
@@ -25919,24 +26686,27 @@ function formatStatus(status2, link, paint2 = plain) {
   lines.push("", ...status2.caveats.map((caveat) => paint2("dim", caveat)));
   return lines.filter((line, index) => line !== "" || lines[index - 1] !== "").join("\n");
 }
-function formatRuns(runs2, paint2 = plain) {
+function formatRuns(runs2, paint2 = plain, width2) {
   if (runs2.length === 0) return "No runs match.";
-  return table([
+  return table(
     [
-      paint2("bold", "RUN"),
-      paint2("bold", "KIND"),
-      paint2("bold", "STATUS"),
-      paint2("bold", "CREATED"),
-      paint2("bold", "TARGET")
+      [
+        paint2("bold", "RUN"),
+        paint2("bold", "KIND"),
+        paint2("bold", "STATUS"),
+        paint2("bold", "CREATED"),
+        paint2("bold", "TARGET")
+      ],
+      ...runs2.map((run2) => [
+        run2.id,
+        runKindLabel(run2),
+        statusColor(run2.status, paint2),
+        date5(run2.createdAt),
+        run2.target
+      ])
     ],
-    ...runs2.map((run2) => [
-      run2.id,
-      runKindLabel(run2),
-      statusColor(run2.status, paint2),
-      date5(run2.createdAt),
-      run2.target
-    ])
-  ]);
+    width2
+  );
 }
 function formatRun(run2, link, paint2 = plain) {
   const lines = [
@@ -25957,7 +26727,25 @@ function formatRun(run2, link, paint2 = plain) {
       "Limits (anything outside them is unknown, not passing):",
       ...run2.coverage.limitations.map((item) => `  - ${item}`)
     );
+  if (run2.exposureCheck) {
+    const [headline, ...limits] = exposureCheckLines(run2.exposureCheck);
+    lines.push(
+      `Exposure   ${headline}`,
+      ...limits.map((item) => `  - ${item}`)
+    );
+  }
   lines.push(paint2("dim", link(run2.webPath)));
+  const open4 = Object.values(run2.open).reduce((sum, count) => sum + count, 0);
+  if (!CLI_TERMINAL_RUN_STATUSES.includes(run2.status))
+    lines.push(next(paint2, `lockpick watch ${run2.id}`));
+  else if (run2.status === "succeeded" && open4 > 0)
+    lines.push(
+      next(
+        paint2,
+        `lockpick findings ${run2.id}`,
+        `lockpick fix ${run2.id} --agent claude`
+      )
+    );
   return lines.join("\n");
 }
 var SEVERITY_STYLE = {
@@ -25967,22 +26755,46 @@ var SEVERITY_STYLE = {
   low: "dim",
   info: "dim"
 };
-function formatFindings(findings2, paint2 = plain) {
-  if (findings2.length === 0) return "No findings need attention.";
-  return table([
-    [
-      paint2("bold", "SEVERITY"),
-      paint2("bold", "STATE"),
-      paint2("bold", "FINDING"),
-      paint2("bold", "TITLE")
-    ],
-    ...findings2.map((finding2) => [
-      paint2(SEVERITY_STYLE[finding2.severity], finding2.severity),
-      finding2.state,
-      finding2.id,
-      finding2.title
-    ])
-  ]);
+function formatFindings(findings2, paint2 = plain, width2) {
+  if (findings2.length === 0)
+    return paint2("green", "No findings need attention.");
+  const bySeverity = CLI_SEVERITIES.map(
+    (severity) => [
+      severity,
+      findings2.filter((finding2) => finding2.severity === severity).length
+    ]
+  ).filter(([, count]) => count > 0);
+  const runId = findings2[0].runId;
+  return [
+    table(
+      [
+        [
+          paint2("bold", "SEVERITY"),
+          paint2("bold", "STATE"),
+          paint2("bold", "TITLE"),
+          paint2("bold", "FINDING")
+        ],
+        ...findings2.map((finding2) => [
+          paint2(SEVERITY_STYLE[finding2.severity], finding2.severity),
+          finding2.state,
+          finding2.title,
+          paint2("dim", finding2.id)
+        ])
+      ],
+      // Titles give way first; a long id is never cut.
+      width2,
+      2
+    ),
+    "",
+    `${plural(findings2.length, "finding")}: ${bySeverity.map(
+      ([severity, count]) => paint2(SEVERITY_STYLE[severity], `${count} ${severity}`)
+    ).join(", ")}`,
+    next(
+      paint2,
+      `lockpick finding ${runId} <finding>`,
+      `lockpick brief ${runId}`
+    )
+  ].join("\n");
 }
 function formatFinding(finding2, link, paint2 = plain) {
   const lines = [
@@ -26318,6 +27130,250 @@ function formatRelevant(tags, paint2 = plain) {
   }
   return lines.join("\n");
 }
+var DOCTOR_MARK = {
+  PASS: ["green", "\u2714"],
+  WARN: ["yellow", "!"],
+  FAIL: ["red", "\u2716"]
+};
+function formatDoctor(checks, paint2 = plain, docsUrl2) {
+  const width2 = Math.max(...checks.map((check3) => check3.name.length));
+  const lines = checks.map((check3) => {
+    const [style, mark] = DOCTOR_MARK[check3.status];
+    return [
+      `${paint2(style, `${mark} ${check3.status}`)}  ${check3.name.padEnd(width2)}  ${check3.detail}`,
+      ...check3.nextStep ? [`${" ".repeat(width2 + 10)}${paint2("dim", `\u2192 ${check3.nextStep}`)}`] : []
+    ].join("\n");
+  });
+  const failed = checks.filter((check3) => check3.status === "FAIL").length;
+  const warned = checks.filter((check3) => check3.status === "WARN").length;
+  lines.push(
+    "",
+    failed ? paint2("red", `${plural(failed, "check")} failed.`) : warned ? paint2("yellow", `Ready, with ${plural(warned, "warning")}.`) : paint2("green", "Everything checks out.")
+  );
+  if (docsUrl2 && (failed || warned))
+    lines.push(paint2("dim", `Help: ${docsUrl2}`));
+  return lines.join("\n");
+}
+function formatDocSearch(search, paint2 = plain) {
+  if (search.results.length === 0)
+    return `No Lockpick docs match "${search.query}".`;
+  return search.results.map(
+    (hit) => [
+      `${paint2("bold", hit.title)}${hit.heading ? paint2("dim", ` \u203A ${hit.heading}`) : ""}`,
+      `  ${hit.snippet.replace(/\s+/g, " ").trim()}`,
+      `  ${paint2("cyan", hit.url)}`
+    ].join("\n")
+  ).join("\n\n");
+}
+
+// src/docs.ts
+var DOCS = {
+  cli: "/docs/cli/install",
+  signIn: "/docs/cli/install#sign-in",
+  exitCodes: "/docs/cli/install#exit-codes",
+  commands: "/docs/cli/commands",
+  configuration: "/docs/cli/configuration",
+  ci: "/docs/cli/ci",
+  permissions: "/docs/mcp/permissions",
+  pulseOrDeep: "/docs/get-started/pulse-or-deep",
+  fix: "/docs/get-started/fix-what-we-found",
+  checkAgain: "/docs/get-started/check-again"
+};
+function docsPageForError(code) {
+  switch (code) {
+    case "UNAUTHENTICATED":
+    case "NO_HOST":
+      return "signIn";
+    case "INSUFFICIENT_SCOPE":
+    case "FORBIDDEN":
+      return "permissions";
+    case "ENTITLEMENT_REQUIRED":
+    case "FEATURE_UNAVAILABLE":
+    case "PROOF_REQUIRED":
+      return "pulseOrDeep";
+    case "NOT_LOCKPICK":
+    case "CONTRACT_MISMATCH":
+    case "NETWORK":
+    case "TIMEOUT":
+      return "configuration";
+    case "VALIDATION_ERROR":
+    case "INVALID_INPUT":
+      return "commands";
+    default:
+      return null;
+  }
+}
+function docsUrl(host, page) {
+  if (!host) return null;
+  try {
+    return new URL(DOCS[page], host).toString();
+  } catch {
+    return null;
+  }
+}
+
+// src/ci.ts
+var FAIL_ON = ["critical", "high", "medium", "low"];
+function failOnArg(value) {
+  if (value === void 0) return void 0;
+  if (FAIL_ON.includes(value)) return value;
+  throw new LockpickApiError(
+    `--fail-on must be one of: ${FAIL_ON.join(", ")}`,
+    400,
+    "VALIDATION_ERROR"
+  );
+}
+function countAtOrAbove(open4, threshold) {
+  return FAIL_ON.slice(0, FAIL_ON.indexOf(threshold) + 1).reduce(
+    (sum, severity) => sum + open4[severity],
+    0
+  );
+}
+function openCounts(findings2) {
+  const counts2 = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const finding2 of findings2)
+    if (finding2.severity !== "info") counts2[finding2.severity]++;
+  return counts2;
+}
+var LOCKPICK_ACTION = {
+  ref: "promptadvisers/lockpick-action@v1",
+  inputs: {
+    host: "host",
+    site: "site",
+    key: "key",
+    failOn: "fail-on"
+  }
+};
+var CI_KEY_SECRET = "LOCKPICK_KEY";
+var CI_WORKFLOW_FILE = ".github/workflows/lockpick.yml";
+var SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+function githubWorkflow(options) {
+  if (!SAFE_ID.test(options.siteId))
+    throw new LockpickApiError(
+      `Site id "${options.siteId}" cannot be written into a workflow.`,
+      400,
+      "VALIDATION_ERROR"
+    );
+  const host = new URL(options.host).origin;
+  const name = options.siteName.replace(/[^\p{L}\p{N} ._-]/gu, "").trim();
+  const step = options.action ? [
+    `      - name: Pulse check of ${name || options.siteId}`,
+    `        uses: ${options.actionRef ?? LOCKPICK_ACTION.ref}`,
+    `        with:`,
+    `          ${LOCKPICK_ACTION.inputs.host}: '${host}'`,
+    `          ${LOCKPICK_ACTION.inputs.site}: '${options.siteId}'`,
+    `          ${LOCKPICK_ACTION.inputs.key}: \${{ secrets.${CI_KEY_SECRET} }}`,
+    `          ${LOCKPICK_ACTION.inputs.failOn}: '${options.failOn}'`
+  ] : [
+    `      - uses: actions/setup-node@v4`,
+    `        with:`,
+    `          node-version: 22`,
+    `      - name: Pulse check of ${name || options.siteId}`,
+    `        env:`,
+    `          LOCKPICK_HOST: '${host}'`,
+    `          LOCKPICK_KEY: \${{ secrets.${CI_KEY_SECRET} }}`,
+    `        run: npx -y lockpicks@${options.cliVersion} pulse ${options.siteId} --no-lockfile --fail-on ${options.failOn} --timeout 900`
+  ];
+  return [
+    `# Lockpick Pulse check, written by \`lockpick ci init\`.`,
+    `# Each run uses one Pulse from your allowance (or 1 credit), so it runs`,
+    `# when you publish a release and when you start it by hand.`,
+    `# It fails when open findings are ${options.failOn} or more severe.`,
+    ...options.docsUrl ? [`# Docs: ${options.docsUrl}`] : [],
+    `name: Lockpick`,
+    `on:`,
+    `  release:`,
+    `    types: [published]`,
+    `  workflow_dispatch:`,
+    `permissions:`,
+    `  contents: read`,
+    `concurrency:`,
+    `  group: lockpick-${options.siteId}`,
+    `  cancel-in-progress: false`,
+    `jobs:`,
+    `  pulse:`,
+    `    name: Lockpick Pulse`,
+    `    runs-on: ubuntu-latest`,
+    `    timeout-minutes: 20`,
+    `    steps:`,
+    ...step,
+    ""
+  ].join("\n");
+}
+function isPrivateHost(host) {
+  const { hostname: hostname4 } = new URL(host);
+  return hostname4 === "localhost" || hostname4.endsWith(".local") || hostname4.endsWith(".ts.net") || /^(127\.|10\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/.test(
+    hostname4
+  ) || hostname4 === "[::1]" || !hostname4.includes(".");
+}
+
+// src/progress.ts
+var FRAMES = ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"];
+function elapsed(ms) {
+  const seconds = Math.floor(ms / 1e3);
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}
+function bar(percent) {
+  const filled = Math.round(Math.min(100, Math.max(0, percent)) / 10);
+  return `${"\u2588".repeat(filled)}${"\u2591".repeat(10 - filled)} ${percent}%`;
+}
+function progress(paint2, options = {}) {
+  const stream = options.stream ?? process.stderr;
+  const now = options.now ?? Date.now;
+  const env = options.env ?? process.env;
+  const started = now();
+  let text2 = "Waiting";
+  let percent = null;
+  if (options.quiet) return { update: () => {
+  }, stop: () => {
+  } };
+  const live = Boolean(stream.isTTY) && env.TERM !== "dumb" && !env.CI;
+  if (!live) {
+    let last = "";
+    return {
+      update: (next2, nextPercent) => {
+        const line = `${next2}${nextPercent != null ? ` (${nextPercent}%)` : ""}`;
+        if (line !== last)
+          stream.write(
+            `${terminalSafe(`${new Date(now()).toISOString().slice(11, 19)}  ${line}`)}
+`
+          );
+        last = line;
+      },
+      stop: (final) => {
+        if (final) stream.write(`${terminalSafe(final)}
+`);
+      }
+    };
+  }
+  let frame = 0;
+  const draw = () => {
+    const room = Math.max(10, (stream.columns ?? 80) - 32);
+    const parts = [
+      paint2("cyan", FRAMES[frame++ % FRAMES.length]),
+      text2.length > room ? `${text2.slice(0, room - 1)}\u2026` : text2,
+      percent != null ? paint2("dim", bar(percent)) : "",
+      paint2("dim", elapsed(now() - started))
+    ].filter(Boolean);
+    const line = terminalSafe(parts.join("  "));
+    stream.write(`\r\x1B[2K${line}`);
+  };
+  const timer = setInterval(draw, 100);
+  timer.unref?.();
+  return {
+    update: (next2, nextPercent) => {
+      text2 = next2;
+      percent = nextPercent ?? null;
+      draw();
+    },
+    stop: (final) => {
+      clearInterval(timer);
+      stream.write("\r\x1B[2K");
+      if (final) stream.write(`${terminalSafe(final)}
+`);
+    }
+  };
+}
 
 // src/login.ts
 var SCOPE_ACCESS = {
@@ -26422,7 +27478,7 @@ import { delimiter, join as join3, sep } from "node:path";
 import { createInterface } from "node:readline/promises";
 
 // src/version.ts
-var CLI_VERSION = true ? "0.3.0" : "0.0.0-dev";
+var CLI_VERSION = true ? "0.4.0" : "0.0.0-dev";
 var CLI_PACKAGE = true ? "lockpicks" : "lockpicks";
 
 // src/install.ts
@@ -34990,6 +36046,13 @@ function renderRun(run2, link) {
       "- Limits (anything outside them is unknown, not passing):",
       ...run2.coverage.limitations.map((item) => `  - ${item}`)
     );
+  if (run2.exposureCheck) {
+    const [headline, ...limits] = exposureCheckLines(run2.exposureCheck);
+    lines.push(
+      `- Exposure check: ${headline}`,
+      ...limits.map((item) => `  - ${item}`)
+    );
+  }
   lines.push(`- Web: ${link(run2.webPath)}`);
   return lines.join("\n");
 }
@@ -35168,9 +36231,72 @@ function levelName(scan) {
   const level = scan.assessmentLevel ?? "pulse";
   return level === "deep" ? "Deep" : level === "standard" ? "Standard" : "Pulse";
 }
+var OUTCOME_REASON = {
+  "no-address": "no DNS address",
+  "dns-error": "the DNS lookup failed",
+  "private-address": "it points to a private network address",
+  refused: "the connection was refused",
+  "no-answer": "the server did not answer in time",
+  "connection-closed": "the server closed the connection",
+  certificate: "the certificate failed the checks a browser makes",
+  "old-tls": "only an old TLS version was offered",
+  "large-headers": "the response headers were over the 64 KB Lockpick reads",
+  "invalid-response": "the response was not valid HTTP",
+  www: "the homepage redirects to its www address",
+  "other-site": "the homepage redirects to another site",
+  "sign-in": "the homepage redirects to a sign-in page",
+  "redirect-loop": "the homepage redirects in a loop",
+  redirect: "the homepage redirect is not one a run follows",
+  "bot-check": "a bot check answered instead of the homepage",
+  denied: "the site refused the request",
+  "rate-limited": "the site asked Lockpick to slow down",
+  "not-found": "the homepage answered not found",
+  gone: "the homepage answered gone",
+  "client-error": "the homepage answered with an error",
+  "server-error": "the server answered with an error",
+  maintenance: "the site is down for maintenance",
+  parked: "the homepage is a parked domain page",
+  empty: "the homepage is empty",
+  "not-html": "the homepage is not an HTML page",
+  "app-shell": "the homepage is an app shell built in the browser",
+  interrupted: "the connection closed while the homepage loaded",
+  "not-delivered": "the run stopped on Lockpick's side before its report was ready"
+};
+var VENDOR_CHECK = {
+  cloudflare: "blocked by Cloudflare's bot check",
+  vercel: "blocked by Vercel's bot check",
+  other: "blocked by a firewall"
+};
+var OUTCOME_LEVEL = {
+  "headers-only": "headers only",
+  blocked: "blocked",
+  transport: "no secure connection",
+  unreachable: "unreachable",
+  "terminal-failure": "did not finish"
+};
+var COVERAGE_TEXT = {
+  page: "pages, their scripts and public records",
+  "headers-and-records": "response headers and public records",
+  "records-only": "public records only",
+  none: "nothing could be collected"
+};
+function outcomeText(outcome) {
+  if (!outcome || outcome.level === "full") return null;
+  if (outcome.level === "blocked" && outcome.reason === "bot-check")
+    return VENDOR_CHECK[outcome.vendor ?? "other"];
+  const reason = outcome.reason ? OUTCOME_REASON[outcome.reason] : null;
+  const status2 = outcome.homepageStatus && outcome.reason !== "rate-limited" ? ` (HTTP ${outcome.homepageStatus})` : "";
+  const contact = outcome.contacted === void 0 ? "" : outcome.contacted ? ", after contacting the site (it counted as a run)" : ", before contacting the site (it did not count as a run)";
+  return `${OUTCOME_LEVEL[outcome.level]}${reason ? `, ${reason}${status2}` : ""}${contact}`;
+}
+var UNFINISHED = /* @__PURE__ */ new Set(["queued", "running", "cancelling"]);
 function headlineText(scan) {
   const { score, grade, letter } = scan.headline;
-  if (score === null) return "no grade yet";
+  if (score === null) {
+    const outcome = outcomeText(scan.outcome);
+    if (outcome) return `not graded, ${outcome}`;
+    return UNFINISHED.has(scan.status) ? "no grade yet" : "not graded";
+  }
   return `${letter ?? ""}${letter ? ", " : ""}${grade ?? "ungraded"}, score ${score}/100`;
 }
 function scanLine(scan) {
@@ -35239,6 +36365,16 @@ function renderScan(scan) {
     lines.push(
       `- Progress: ${inlineText(scan.progress.message, 200)}${scan.progress.percent !== null ? ` (${scan.progress.percent}%)` : ""}`
     );
+  if (scan.outcome)
+    lines.push(`- Based on: ${COVERAGE_TEXT[scan.outcome.coverage]}`);
+  if (scan.outcome?.level === "blocked")
+    lines.push(
+      `- Lockpick never tries to get past a bot check or firewall. The owner can let it through: ${new URL("/docs/protect/firewall", scan.webUrl).href}`
+    );
+  if (scan.outcome?.redirectOrigin)
+    lines.push(
+      `- Check instead: ${codeSpan(scan.outcome.redirectOrigin)} (the address the homepage redirects to)`
+    );
   if (scan.coverage.percent !== null)
     lines.push(`- Coverage: ${scan.coverage.percent}%`);
   if (scan.coverage.limitations.length)
@@ -35246,6 +36382,13 @@ function renderScan(scan) {
       "- Limits (anything outside them is unknown, not passing):",
       ...scan.coverage.limitations.slice(0, 10).map((item) => `  - ${inlineText(item, 300)}`)
     );
+  if (scan.exposureCheck) {
+    const [headline, ...limits] = exposureCheckLines(scan.exposureCheck);
+    lines.push(
+      `- Exposure check: ${headline}`,
+      ...limits.map((item) => `  - ${item}`)
+    );
+  }
   lines.push(`- Web: ${scan.webUrl}`);
   if (scan.suggestedPollAfterSeconds !== null)
     lines.push(
@@ -36433,12 +37576,12 @@ var startsPulse = {
 function runResult(backend, run2, format3) {
   if (format3 === "json") return json2(run2);
   const body = renderRun(run2, (path) => backend.webUrl(path));
-  const next = CLI_TERMINAL_RUN_STATUSES.includes(run2.status) ? run2.baselineRunId && run2.status === "succeeded" ? `
+  const next2 = CLI_TERMINAL_RUN_STATUSES.includes(run2.status) ? run2.baselineRunId && run2.status === "succeeded" ? `
 
 This was a recheck of \`${run2.baselineRunId}\`. Call lockpick_compare_runs with runId \`${run2.id}\` to see what changed.` : "" : `
 
 Still ${run2.status}. Call lockpick_wait_for_run with runId \`${run2.id}\` to keep waiting.`;
-  return text(body + next);
+  return text(body + next2);
 }
 var whoamiTool = defineTool({
   name: "lockpick_whoami",
@@ -36879,9 +38022,9 @@ function pollSeconds(value) {
     );
   return seconds;
 }
-function progressLine(run2) {
+function progressLine(run2, withPercent = true) {
   const message = run2.progress?.message ? ` \xB7 ${run2.progress.message}` : "";
-  const percent = run2.progress?.percent != null ? ` (${run2.progress.percent}%)` : "";
+  const percent = withPercent && run2.progress?.percent != null ? ` (${run2.progress.percent}%)` : "";
   return `${run2.status}${message}${percent}`;
 }
 
@@ -37118,28 +38261,47 @@ var common = {
   }
 };
 var paint = painter();
-var out = (text2) => void process.stdout.write(`${text2}
+var epaint = painter(process.stderr);
+var out = (text2) => void process.stdout.write(`${terminalSafe(text2)}
 `);
-var err = (text2) => void process.stderr.write(`${text2}
+var err = (text2) => void process.stderr.write(`${terminalSafe(text2)}
 `);
+var width = () => terminalWidth(process.stdout);
 var sleep = (ms) => new Promise((resolve6) => setTimeout(resolve6, ms));
 process.stdout.on("error", (error51) => {
   if (error51.code === "EPIPE") process.exit(EXIT.ok);
   throw error51;
 });
+async function knownHost() {
+  const flag = process.argv.indexOf("--host");
+  const explicit = (flag > -1 ? process.argv[flag + 1] : void 0) ?? process.argv.find((arg) => arg.startsWith("--host="))?.slice(7) ?? process.env.LOCKPICK_HOST;
+  try {
+    if (explicit) return normalizeHost(explicit);
+    return (await new CredentialStore().profile())?.host ?? null;
+  } catch {
+    return null;
+  }
+}
+var docsLink = async (page) => docsUrl(await knownHost(), page);
 async function action(work) {
   try {
     await work();
   } catch (error51) {
     const apiError = error51 instanceof LockpickApiError ? error51 : null;
-    const message = error51 instanceof Error ? error51.message : String(error51);
+    const message = neutralize(
+      error51 instanceof Error ? error51.message : String(error51)
+    );
     process.exitCode = exitCodeFor(error51);
     const agentError = apiError?.agentError ?? null;
+    const code = agentError?.code ?? apiError?.code ?? null;
+    const page = docsPageForError(code);
+    const help = page ? await docsLink(page) : null;
     if (process.argv.includes("--json"))
       err(
         JSON.stringify({
           error: agentError?.message ?? message,
-          code: agentError?.code ?? apiError?.code ?? null,
+          code,
+          ...help ? { docsUrl: help } : {},
           ...agentError ? {
             nextStep: agentError.nextStep,
             retryAfterSeconds: agentError.retryAfterSeconds,
@@ -37151,10 +38313,11 @@ async function action(work) {
     else {
       const [first, ...rest] = formatErrorLines(
         agentError?.message ?? message,
-        agentError
+        agentError,
+        help
       );
-      err(paint("red", first));
-      for (const line of rest) err(line);
+      err(epaint("red", `\u2716 ${first}`));
+      for (const line of rest) err(`  ${line}`);
     }
   }
 }
@@ -37173,6 +38336,46 @@ function parse3(schema, value, name, allowed) {
     );
   }
 }
+var NOT_IN_IDS = /[\u0000-\u001f\u007f\s]/;
+function idArg(value, name) {
+  if (/^\.{1,2}$/.test(value) || NOT_IN_IDS.test(value) || !value || value.length > 300)
+    throw new LockpickApiError(
+      `${name} "${neutralize(value).slice(0, 60)}" is not a valid id. Copy it from \`lockpick runs\` or \`lockpick findings\`.`,
+      400,
+      "VALIDATION_ERROR"
+    );
+  return value;
+}
+function limitArg(value) {
+  if (value === void 0) return void 0;
+  const limit = Number(value);
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+    throw new LockpickApiError(
+      "--limit must be a whole number from 1 to 100.",
+      400,
+      "VALIDATION_ERROR"
+    );
+  return limit;
+}
+var failOnFlag = {
+  failOn: {
+    type: "string",
+    description: `Exit 8 when open findings are this severe or worse: ${FAIL_ON.join(", ")} (for CI)`
+  }
+};
+function gate(open4, threshold, json3) {
+  if (!threshold) return;
+  const count = countAtOrAbove(open4, threshold);
+  if (count === 0) return;
+  if (!json3)
+    err(
+      epaint(
+        "red",
+        `\u2716 ${count} open ${count === 1 ? "finding is" : "findings are"} ${threshold} or more severe (--fail-on ${threshold}).`
+      )
+    );
+  process.exitCode = EXIT.findings;
+}
 function agentArg(value) {
   if (value === void 0) return void 0;
   if (isPromptAgent(value)) return value;
@@ -37229,17 +38432,16 @@ var login = defineCommand({
   run: ({ args }) => action(async () => {
     const store = new CredentialStore();
     const explicit = args.host ?? process.env.LOCKPICK_HOST;
-    const host = explicit ? normalizeHost(explicit) : (await store.profile())?.host;
+    let host = explicit ? normalizeHost(explicit) : (await store.profile())?.host;
     if (!host)
       throw new LockpickApiError(
         "Which Lockpick? Run `lockpick login --host <url>`.",
         400,
         "NO_HOST"
       );
-    const client = new LockpickClient(host, null);
     const requested = requestedScopes(args);
-    const approved = await deviceLogin(
-      client,
+    const login2 = (at) => deviceLogin(
+      new LockpickClient(at, null),
       {
         clientName: "Lockpick CLI",
         hostname: hostname3(),
@@ -37248,8 +38450,20 @@ var login = defineCommand({
         scopes: requested
       },
       { print: args.json ? err : out, openBrowser, sleep },
-      { browser: args.browser, host }
+      { browser: args.browser, host: at }
     );
+    let approved;
+    try {
+      approved = await login2(host);
+    } catch (error51) {
+      if (!(error51 instanceof HostRedirectError) || !error51.canonicalHost)
+        throw error51;
+      (args.json ? err : out)(
+        `${host} redirects to ${error51.canonicalHost}; signing in there.`
+      );
+      host = error51.canonicalHost;
+      approved = await login2(host);
+    }
     const { inKeychain } = await store.save({
       host,
       workspace: approved.workspace,
@@ -37354,14 +38568,8 @@ var doctor = defineCommand({
       host: args.host,
       scope: args.scope
     });
-    emit(
-      args.json,
-      checks,
-      () => checks.map(
-        (check3) => `[${check3.status}] ${check3.name}: ${check3.detail}${check3.nextStep ? `
-       ${check3.nextStep}` : ""}`
-      ).join("\n")
-    );
+    const help = await docsLink("cli");
+    emit(args.json, checks, () => formatDoctor(checks, paint, help));
     if (checks.some((check3) => check3.status === "FAIL")) process.exitCode = 1;
   })
 });
@@ -37374,7 +38582,7 @@ var projects = defineCommand({
   run: ({ args }) => action(async () => {
     const client = await clientFor({ host: args.host });
     const list = await client.listProjects();
-    emit(args.json, list, () => formatProjects(list, paint));
+    emit(args.json, list, () => formatProjects(list, paint, width()));
   })
 });
 var lockfileArg = {
@@ -37487,7 +38695,11 @@ var status = defineCommand({
     const client = await clientFor({ host: args.host });
     if (!args.project) {
       const list = await client.listProjects();
-      return emit(args.json, list, () => formatProjects(list, paint));
+      return emit(
+        args.json,
+        list,
+        () => formatProjects(list, paint, width())
+      );
     }
     const project = await findProject(client, args.project);
     const report = await client.projectStatus(project.id);
@@ -37526,9 +38738,9 @@ var runs = defineCommand({
         "status",
         CLI_RUN_STATUSES
       ),
-      limit: args.limit ? Number(args.limit) : void 0
+      limit: limitArg(args.limit)
     });
-    emit(args.json, list, () => formatRuns(list, paint));
+    emit(args.json, list, () => formatRuns(list, paint, width()));
   })
 });
 var run = defineCommand({
@@ -37539,7 +38751,7 @@ var run = defineCommand({
   },
   run: ({ args }) => action(async () => {
     const client = await clientFor({ host: args.host });
-    const detail = await client.getRun(args.runId);
+    const detail = await client.getRun(idArg(args.runId, "Run"));
     emit(
       args.json,
       detail,
@@ -37548,18 +38760,19 @@ var run = defineCommand({
   })
 });
 async function follow(client, runId, args) {
-  let last = "";
-  const run2 = await waitForRun(client, runId, {
-    intervalMs: pollSeconds(args.interval) * 1e3,
-    timeoutMs: waitSeconds(args.timeout, 600) * 1e3,
-    sleep,
-    onUpdate: (update) => {
-      const line = progressLine(update);
-      if (line !== last && !args.json)
-        err(`${(/* @__PURE__ */ new Date()).toISOString().slice(11, 19)}  ${line}`);
-      last = line;
-    }
-  });
+  const threshold = failOnArg(args.failOn);
+  const live = progress(epaint, { quiet: args.json });
+  let run2;
+  try {
+    run2 = await waitForRun(client, runId, {
+      intervalMs: pollSeconds(args.interval) * 1e3,
+      timeoutMs: waitSeconds(args.timeout, 600) * 1e3,
+      sleep,
+      onUpdate: (update) => live.update(progressLine(update, false), update.progress?.percent)
+    });
+  } finally {
+    live.stop();
+  }
   emit(
     args.json,
     run2,
@@ -37570,6 +38783,7 @@ async function follow(client, runId, args) {
       `Wait ended; ${run2.id} is still ${run2.status}. Resume with lockpick watch ${run2.id}.`
     );
   if (run2.status !== "succeeded") process.exitCode = EXIT.unfinished;
+  else gate(run2.open, threshold, args.json);
 }
 var watch = defineCommand({
   meta: {
@@ -37578,6 +38792,7 @@ var watch = defineCommand({
   },
   args: {
     runId: { type: "positional", description: "Run id", required: true },
+    ...failOnFlag,
     interval: {
       type: "string",
       description: "Seconds between checks (default 5, backs off to 30)"
@@ -37589,8 +38804,9 @@ var watch = defineCommand({
     ...common
   },
   run: ({ args }) => action(async () => {
+    failOnArg(args.failOn);
     const client = await clientFor({ host: args.host });
-    await follow(client, args.runId, args);
+    await follow(client, idArg(args.runId, "Run"), args);
   })
 });
 var pulse = defineCommand({
@@ -37617,12 +38833,14 @@ var pulse = defineCommand({
       type: "string",
       description: "Maximum wait in seconds (default 600, max 3600)"
     },
+    ...failOnFlag,
     ...lockfileArg,
     ...common
   },
   run: ({ args }) => action(async () => {
     pollSeconds(args.interval);
     waitSeconds(args.timeout, 600);
+    failOnArg(args.failOn);
     const client = await clientFor({ host: args.host });
     const project = await findProject(client, args.project);
     const run2 = await client.startPulse(project.id, randomUUID6());
@@ -37635,7 +38853,7 @@ var pulse = defineCommand({
       );
     if (!args.json)
       err(
-        `Started Pulse ${run2.id} on ${run2.target}${run2.baselineRunId ? ` (recheck of ${run2.baselineRunId})` : ""}.`
+        `${epaint("green", "\u2714")} Started Pulse ${run2.id} on ${run2.target}${run2.baselineRunId ? ` (recheck of ${run2.baselineRunId})` : ""}.`
       );
     await follow(client, run2.id, args);
   })
@@ -37670,15 +38888,21 @@ var check2 = defineCommand({
       idempotencyKey: randomUUID6()
     });
     const deadline = Date.now() + timeout * 1e3;
-    while (args.wait && (result.status === "queued" || result.status === "running") && Date.now() < deadline) {
-      await sleep(
-        Math.min(
-          (result.suggestedPollAfterSeconds ?? 5) * 1e3,
-          deadline - Date.now()
-        )
-      );
-      if (Date.now() >= deadline) break;
-      result = await client.agent.getQuickCheck(result.checkId);
+    const live = progress(epaint, { quiet: args.json || !args.wait });
+    try {
+      while (args.wait && (result.status === "queued" || result.status === "running") && Date.now() < deadline) {
+        live.update(`Quick check of ${args.url} \xB7 ${result.status}`);
+        await sleep(
+          Math.min(
+            (result.suggestedPollAfterSeconds ?? 5) * 1e3,
+            deadline - Date.now()
+          )
+        );
+        if (Date.now() >= deadline) break;
+        result = await client.agent.getQuickCheck(result.checkId);
+      }
+    } finally {
+      live.stop();
     }
     emit(args.json, result, () => formatQuickCheck(result, paint));
     if (args.wait && (result.status === "queued" || result.status === "running"))
@@ -37737,8 +38961,10 @@ var sitesSwitch = defineCommand({
   },
   run: ({ args }) => action(async () => {
     if (!args.yes)
-      throw new Error(
-        `This removes site ${args.site} from monitoring. Run it again with --yes to confirm.`
+      throw new LockpickApiError(
+        `This removes site ${args.site} from monitoring. Run it again with --yes to confirm.`,
+        400,
+        "VALIDATION_ERROR"
       );
     const client = await clientFor({ host: args.host });
     const switched = await client.agent.switchFreeSite({
@@ -37762,7 +38988,7 @@ var sites = defineCommand({
     return action(async () => {
       const client = await clientFor({ host: args.host });
       const list = await client.listProjects();
-      emit(args.json, list, () => formatProjects(list, paint));
+      emit(args.json, list, () => formatProjects(list, paint, width()));
     });
   }
 });
@@ -37794,23 +39020,33 @@ var recheck = defineCommand({
       type: "string",
       description: "Maximum wait in seconds (default 600, max 3600)"
     },
+    ...failOnFlag,
     ...lockfileArg,
     ...common
   },
   run: ({ args }) => action(async () => {
     pollSeconds(args.interval);
     waitSeconds(args.timeout, 600);
+    failOnArg(args.failOn);
     const client = await clientFor({ host: args.host });
     if (args.dns) {
+      idArg(args.target, "Scan");
+      idArg(args.dns, "Finding");
       let result = await client.agent.recheckDns(args.target, {
         findingId: args.dns,
         idempotencyKey: randomUUID6()
       });
       const deadline = Date.now() + waitSeconds(args.timeout, 60) * 1e3;
-      while (args.wait && result.pending && Date.now() < deadline) {
-        await sleep(Math.min(3e3, deadline - Date.now()));
-        if (Date.now() >= deadline) break;
-        result = await client.agent.getDnsRecheck(args.target);
+      const live = progress(epaint, { quiet: args.json || !args.wait });
+      try {
+        while (args.wait && result.pending && Date.now() < deadline) {
+          live.update(`Reading DNS records again for ${args.dns}`);
+          await sleep(Math.min(3e3, deadline - Date.now()));
+          if (Date.now() >= deadline) break;
+          result = await client.agent.getDnsRecheck(args.target);
+        }
+      } finally {
+        live.stop();
       }
       emit(args.json, result, () => formatDnsRecheck(result, paint));
       if (args.wait && result.pending) {
@@ -37908,7 +39144,7 @@ var verifyCommand = (name, description) => defineCommand({
           "Not seen. Once it is published, run lockpick verify again. The value stays the same."
         )
       );
-    process.exitCode = 3;
+    process.exitCode = EXIT.unfinished;
   })
 });
 var deepVerify = verifyCommand(
@@ -37942,14 +39178,14 @@ var deepCheck = defineCommand({
     const project = await findProject(client, args.site);
     const verification = await client.agent.checkDeepVerification(
       project.id,
-      args.verificationId
+      idArg(args.verificationId, "Proof")
     );
     emit(
       args.json,
       verification,
       () => formatVerification(verification, paint)
     );
-    if (verification.state !== "verified") process.exitCode = 3;
+    if (verification.state !== "verified") process.exitCode = EXIT.unfinished;
   })
 });
 var deepPrepare = defineCommand({
@@ -37979,7 +39215,7 @@ var deepPrepare = defineCommand({
     const client = await clientFor({ host: args.host });
     const project = await findProject(client, args.site);
     const prepared = await client.agent.prepareDeep(project.id, {
-      verificationId: args.verificationId,
+      verificationId: idArg(args.verificationId, "Proof"),
       idempotencyKey: randomUUID6()
     });
     emit(args.json, prepared, () => formatPreparedDeep(prepared, paint));
@@ -38011,13 +39247,17 @@ var deepStart = defineCommand({
       type: "string",
       description: "Maximum wait in seconds (default 600, max 3600)"
     },
+    ...failOnFlag,
     ...common
   },
   run: ({ args }) => action(async () => {
     pollSeconds(args.interval);
     waitSeconds(args.timeout, 600);
+    failOnArg(args.failOn);
     const client = await clientFor({ host: args.host });
-    const launch = await client.agent.startDeep(args.operationId);
+    const launch = await client.agent.startDeep(
+      idArg(args.operationId, "Operation")
+    );
     const started = `Started Deep scan ${launch.scan.id} on ${launch.scan.target}. ${chargeText(launch)}`;
     if (!args.wait)
       return emit(
@@ -38055,11 +39295,13 @@ var findings = defineCommand({
       description: "Include passing and not-assessed checks",
       default: false
     },
+    ...failOnFlag,
     ...common
   },
   run: ({ args }) => action(async () => {
+    const threshold = failOnArg(args.failOn);
     const client = await clientFor({ host: args.host });
-    const list = await client.listFindings(args.runId, {
+    const list = await client.listFindings(idArg(args.runId, "Run"), {
       severity: parse3(
         cliSeveritySchema,
         args.severity,
@@ -38068,7 +39310,12 @@ var findings = defineCommand({
       ),
       all: args.all
     });
-    emit(args.json, list, () => formatFindings(list, paint));
+    emit(args.json, list, () => formatFindings(list, paint, width()));
+    gate(
+      openCounts(list.filter((item) => item.state === "attention")),
+      threshold,
+      args.json
+    );
   })
 });
 var finding = defineCommand({
@@ -38084,7 +39331,10 @@ var finding = defineCommand({
   },
   run: ({ args }) => action(async () => {
     const client = await clientFor({ host: args.host });
-    const detail = await client.getFinding(args.runId, args.findingId);
+    const detail = await client.getFinding(
+      idArg(args.runId, "Run"),
+      idArg(args.findingId, "Finding")
+    );
     emit(
       args.json,
       detail,
@@ -38107,7 +39357,11 @@ var brief = defineCommand({
   run: ({ args }) => action(async () => {
     const agent2 = agentArg(args.agent);
     const client = await clientFor({ host: args.host });
-    const result = await client.repairBrief(args.runId, args.finding, agent2);
+    const result = await client.repairBrief(
+      idArg(args.runId, "Run"),
+      args.finding === void 0 ? void 0 : idArg(args.finding, "Finding"),
+      agent2
+    );
     if (args.out) {
       await writeFile2(args.out, `${result.markdown}
 `);
@@ -38139,7 +39393,11 @@ var fix = defineCommand({
   run: ({ args }) => action(async () => {
     const agent2 = agentArg(args.agent);
     const client = await clientFor({ host: args.host });
-    const result = await client.repairBrief(args.runId, void 0, agent2);
+    const result = await client.repairBrief(
+      idArg(args.runId, "Run"),
+      void 0,
+      agent2
+    );
     if (result.findingIds.length === 0) {
       if (args.json)
         return emit(true, { ...result, file: null, command: null }, () => "");
@@ -38178,7 +39436,7 @@ var compare = defineCommand({
   },
   run: ({ args }) => action(async () => {
     const client = await clientFor({ host: args.host });
-    const comparison = await client.comparison(args.runId);
+    const comparison = await client.comparison(idArg(args.runId, "Run"));
     emit(args.json, comparison, () => formatComparison(comparison, paint));
   })
 });
@@ -38411,6 +39669,159 @@ var skills = defineCommand({
       );
   })
 });
+var docs = defineCommand({
+  meta: {
+    name: "docs",
+    description: "Search the Lockpick docs from the terminal, or list the CLI guides (--open opens the first match)"
+  },
+  args: {
+    query: {
+      type: "positional",
+      description: 'What to look for, e.g. "fix a missing CSP"',
+      required: false
+    },
+    open: {
+      type: "boolean",
+      description: "Open the best match (or the CLI guide) in the browser",
+      default: false
+    },
+    ...common
+  },
+  run: ({ args, rawArgs }) => action(async () => {
+    const hostValue = rawArgs.indexOf("--host") + 1;
+    const query = rawArgs.filter(
+      (arg, index) => !arg.startsWith("-") && (hostValue === 0 || index !== hostValue)
+    ).join(" ").trim();
+    if (!query) {
+      const session = await resolveSession({ host: args.host });
+      const pages = [
+        ["Install and sign in", "cli"],
+        ["Every command", "commands"],
+        ["Keys and environment", "configuration"],
+        ["Run Lockpick in CI", "ci"],
+        ["What each permission allows", "permissions"],
+        ["Pulse or Deep", "pulseOrDeep"],
+        ["Fix what Lockpick found", "fix"]
+      ].map(([title, page]) => ({
+        title,
+        url: docsUrl(session.host, page)
+      }));
+      emit(
+        args.json,
+        pages,
+        () => [
+          ...pages.map(
+            (page) => `${page.title.padEnd(28)} ${paint("cyan", page.url)}`
+          ),
+          "",
+          paint("dim", "Search them with: lockpick docs <words>")
+        ].join("\n")
+      );
+      if (args.open && !args.json) await openBrowser(pages[0].url);
+      return;
+    }
+    const client = await clientFor({ host: args.host });
+    const found = await client.agent.searchDocs({ query, limit: 5 });
+    emit(args.json, found, () => formatDocSearch(found, paint));
+    if (args.open && !args.json && found.results[0])
+      await openBrowser(found.results[0].url);
+  })
+});
+var ciInit = defineCommand({
+  meta: {
+    name: "init",
+    description: `Write a GitHub Actions workflow (${CI_WORKFLOW_FILE}) that runs a Pulse on each release and fails on serious findings`
+  },
+  args: {
+    site: {
+      type: "positional",
+      description: "Site id or name to check",
+      required: true
+    },
+    failOn: {
+      type: "string",
+      description: `Fail the workflow at this severity or worse: ${FAIL_ON.join(", ")} (default high)`,
+      default: "high"
+    },
+    file: {
+      type: "string",
+      description: `Where to write it (default ${CI_WORKFLOW_FILE})`
+    },
+    action: {
+      type: "boolean",
+      description: "Use the Lockpick GitHub Action instead of running the CLI with npx (preview)",
+      default: false
+    },
+    force: {
+      type: "boolean",
+      description: "Replace an existing workflow file",
+      default: false
+    },
+    dryRun: {
+      type: "boolean",
+      description: "Print the workflow instead of writing it",
+      default: false
+    },
+    ...common
+  },
+  run: ({ args }) => action(async () => {
+    const failOn = failOnArg(args.failOn) ?? "high";
+    const client = await clientFor({ host: args.host });
+    const project = await findProject(client, args.site);
+    const workflow = githubWorkflow({
+      host: client.host,
+      siteId: project.id,
+      siteName: project.name,
+      failOn,
+      cliVersion: CLI_VERSION,
+      docsUrl: docsUrl(client.host, "ci"),
+      action: args.action,
+      actionRef: process.env.LOCKPICK_ACTION_REF
+    });
+    const file2 = args.file ?? CI_WORKFLOW_FILE;
+    const warnings = isPrivateHost(client.host) ? [
+      `${client.host} is not reachable from GitHub-hosted runners. Use your public Lockpick address with --host, or a self-hosted runner.`
+    ] : [];
+    if (args.dryRun)
+      return emit(args.json, { file: file2, workflow, warnings }, () => workflow);
+    if (!args.force && await access2(file2).then(
+      () => true,
+      () => false
+    ))
+      throw new LockpickApiError(
+        `${file2} already exists. Pass --force to replace it, or --dry-run to see the new one.`,
+        400,
+        "VALIDATION_ERROR"
+      );
+    await mkdir4(dirname5(file2), { recursive: true });
+    await writeFile2(file2, workflow);
+    emit(
+      args.json,
+      { file: file2, workflow, warnings },
+      () => [
+        `${paint("green", "\u2714")} Wrote ${file2} for ${project.name} (${project.id}).`,
+        ...warnings.map((warning) => paint("yellow", `! ${warning}`)),
+        "",
+        "Next:",
+        `  1. Save a Lockpick key allowed to start Pulses as the repository secret ${CI_KEY_SECRET}:`,
+        `     gh secret set ${CI_KEY_SECRET}`,
+        `  2. Commit ${file2}, then run it from the Actions tab or publish a release.`,
+        paint(
+          "dim",
+          `Each run uses one Pulse (or 1 credit). It fails on ${failOn} findings or worse.`
+        ),
+        ...docsUrl(client.host, "ci") ? [paint("dim", `Docs: ${docsUrl(client.host, "ci")}`)] : []
+      ].join("\n")
+    );
+  })
+});
+var ci = defineCommand({
+  meta: {
+    name: "ci",
+    description: "Run Lockpick in CI: `lockpick ci init <site>` writes a GitHub Actions workflow"
+  },
+  subCommands: { init: ciInit }
+});
 var main = defineCommand({
   meta: {
     name: "lockpick",
@@ -38442,7 +39853,9 @@ var main = defineCommand({
     import: importFindings,
     open: open3,
     mcp,
-    skills
+    skills,
+    docs,
+    ci
   }
 });