@chainpatrol/sdk 0.8.0 → 0.9.0

package/dist/skill/cli.js

@@ -0,0 +1,1689 @@
+#!/usr/bin/env node
+'use strict';
+
+var fs = require('fs');
+var path = require('path');
+var os = require('os');
+var url = require('url');
+
+// src/skill/content.ts
+function buildSkillContent(version) {
+  return `---
+name: chainpatrol
+version: ${version}
+description: |
+  ChainPatrol CLI assistant. Helps use the chainpatrol CLI tool: login via device
+  code flow, check auth status, list detection configs, list reports (including
+  customer-reported ones), run CLI commands, and run an organization
+  healthcheck across the detection / reviewing / blocklisting / takedown
+  pipeline.
+  Use when: "chainpatrol cli", "login to chainpatrol", "check detection configs",
+  "am I logged in", "list configs", "use the cli", "list reports",
+  "customer reports", "reports reported by customer", "find detection gaps",
+  "org healthcheck", "organization health check", "audit my org",
+  "what's wrong with org", "review org setup", "list orgs", "list organizations",
+  "get org", "get organization", "show org details", "org by slug",
+  "fetch org details", "org info",
+  "orgs with takedowns off", "automation off across orgs",
+  "which customers have X enabled", "service toggles by org",
+  "obligatory admin approval", "obligatory organization admin approval",
+  "obligatory approval", "admin approval enabled", "admin approval orgs",
+  "requires customer review", "requires admin approval",
+  "orgs that require admin approval", "orgs requiring approval",
+  "which orgs require approval for twitter", "approval scope",
+  "admin approval asset types", "approval per asset type",
+  "pending approval", "pending approvals", "pending service approval",
+  "orgs with pending approval", "pending wallet blocking approval",
+  "pending takedown approval", "awaiting approval", "waiting for approval",
+  "is protection active approval", "wallet blocking approval",
+  "who needs to approve wallet blocking", "service change request",
+  "track orgs with pending approval", "orgs awaiting sign-off",
+  "is this URL blocked", "is this domain blocked", "is this address blocked",
+  "check this asset", "asset check", "lookup asset status",
+  "what is ARCHIVE_ORG", "what does PAGE mean", "list asset types",
+  "supported asset types", "asset type mapping", "asset type enum",
+  "what asset types are there", "human readable asset type",
+  "how many takedowns", "takedowns in the last", "threats taken down",
+  "across all clients", "across all customers", "across all orgs",
+  "across all brands", "company-wide", "total takedowns", "total threats",
+  "total reports", "average takedowns", "average threats", "average per day",
+  "average per customer", "average per org", "rollup across customers",
+  "sum across orgs", "sum across customers",
+  "trends in org", "search for trends", "trend search", "look for trends",
+  "any trends", "trending threats", "spike in asset type",
+  "spike in threat volume", "coordinated attack", "spike check",
+  "anything unusual", "anything new for", "what's new for",
+  "employee being targeted", "spike on a sub-brand", "spike on a brand",
+  "sub-brand spike",
+  "list brands", "brands for org", "list sub-brands", "employee brands",
+  "individual brands", "brand list", "all brands in org".
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# ChainPatrol CLI Skill
+
+You are a ChainPatrol CLI assistant. Help the user interact with the ChainPatrol
+platform using the CLI tool.
+
+## Running the CLI
+
+IMPORTANT: Claude Code's sandbox shell often has a minimal PATH
+(\`/usr/bin:/bin:/usr/sbin:/sbin\`) that may not include the directory where
+\`chainpatrol\` is installed, so bare \`chainpatrol\` calls may fail with
+"command not found". Always invoke the CLI by its full path.
+
+The install location depends on the environment:
+
+- **Local installs** typically land at \`/usr/local/bin/chainpatrol\` (when
+  installed globally via \`npm install -g @chainpatrol/cli\`).
+- **Cloud / sandboxed environments** (e.g. Claude Code on the web, Cursor
+  Cloud) often install Node into \`/opt\` and the binary ends up under a
+  Node-version-specific path like \`/opt/node22/bin/chainpatrol\`. Variants
+  such as \`/opt/node20/bin/chainpatrol\` or \`/opt/node21/bin/chainpatrol\`
+  are also possible depending on which Node version is active.
+
+To find the binary, try (in order):
+
+\`\`\`bash
+command -v chainpatrol \\
+  || ls /usr/local/bin/chainpatrol /opt/node*/bin/chainpatrol 2>/dev/null \\
+  | head -n 1
+\`\`\`
+
+Then use that full path for every subsequent command, e.g.:
+
+\`\`\`bash
+/opt/node22/bin/chainpatrol <command> [options]
+# or
+/usr/local/bin/chainpatrol <command> [options]
+\`\`\`
+
+All examples below use the short name \`chainpatrol\` for readability, but you
+MUST substitute the full resolved path in your Bash commands.
+
+## Available Commands
+
+### \`login\` \u2014 Authenticate with ChainPatrol
+
+Uses the OAuth Device Code flow (RFC 8628):
+1. CLI requests a device code from the server
+2. User is shown a code and a URL to visit
+3. User authorizes in the browser
+4. CLI polls for the token
+
+\`\`\`bash
+chainpatrol login
+\`\`\`
+
+JSON mode (for automation):
+\`\`\`bash
+chainpatrol --json login
+\`\`\`
+
+#### Running \`login\` from an agent (headless / non-TTY)
+
+The login flow blocks for up to 30 minutes while polling for the user to
+authorize in their browser. If you (the agent) run it as a foreground
+command and wait for it to exit before reading output, you will appear
+stuck \u2014 the verification URL will never be shown because the process is
+still polling.
+
+**Always run \`login\` in the background and stream its output**, then
+surface the verification URL to the user as soon as it appears:
+
+\`\`\`bash
+# 1. Kick off login in the background (do NOT wait for it to exit)
+chainpatrol --json login > /tmp/cp-login.out 2>&1 &
+
+# 2. Wait briefly for the first line, which contains the URL
+for _ in 1 2 3 4 5 6 7 8 9 10; do
+  test -s /tmp/cp-login.out && break
+  sleep 1
+done
+cat /tmp/cp-login.out
+\`\`\`
+
+The first line emitted is JSON describing the device code, e.g.:
+
+\`\`\`json
+{"action":"open_url","user_code":"ABCD-1234","verification_uri":"https://app.chainpatrol.io/auth/verify-device","verification_uri_complete":"https://app.chainpatrol.io/auth/verify-device?user_code=ABCD-1234","expires_in":1800,"headless":true}
+\`\`\`
+
+Show the user the \`verification_uri_complete\` link (or
+\`verification_uri\` + \`user_code\` as a fallback) and explain that the
+CLI will pick up the token automatically once they authorize. Then keep
+the background process running and tail it for the final
+\`{"status":"success",...}\` or \`{"error":...}\` line.
+
+CLI v0.3.3+ also auto-detects non-TTY stdout and prints the URL as plain
+text immediately when you run \`chainpatrol login\` without \`--json\`,
+so the same background+tail pattern works without \`--json\`. Prefer
+\`--json\` so the output is structured and machine-parseable.
+
+### \`logout\` \u2014 Clear stored credentials
+
+\`\`\`bash
+chainpatrol logout
+\`\`\`
+
+### \`asset check\` \u2014 Check one or many assets against the blocklist
+
+Look up a URL, domain, or crypto address and return its aggregated status
+(\`BLOCKED\`, \`ALLOWED\`, or \`UNKNOWN\`) plus a per-source breakdown
+(ChainPatrol + external feeds like eth-phishing-detect, phishfort, seal,
+polkadot-phishing). Works whether you're authenticated via device-code
+login or via a \`CHAINPATROL_API_KEY\` env var.
+
+Single asset:
+
+\`\`\`bash
+chainpatrol asset check https://phish.example
+chainpatrol asset check 0xabc123...
+\`\`\`
+
+#### Bulk checks (preferred for >1 asset)
+
+Pass multiple assets in a single invocation \u2014 the CLI runs them in
+parallel (concurrency 10) and returns one row per asset. **Do this
+instead of looping the CLI in a shell \`for\` loop**: one process, one
+auth handshake, parallel HTTP. Use either positional args or repeated
+\`--asset\`:
+
+\`\`\`bash
+# positional form
+chainpatrol asset check a.example b.example c.example
+
+# repeated --asset (handy when content has spaces or special chars)
+chainpatrol asset check --asset a.example --asset b.example
+
+# from a file of one-asset-per-line (use xargs to splat into one call)
+xargs -a domains.txt chainpatrol asset check
+\`\`\`
+
+JSON mode is the agent-friendly default \u2014 single-asset JSON keeps the
+flat \`{ content, status, source, reason?, sources[], watchStatus? }\`
+shape; multi-asset JSON returns \`{ results: [...], summary: { checked,
+blocked, allowed, unknown, errored } }\`:
+
+\`\`\`bash
+chainpatrol --json asset check https://phish.example
+chainpatrol --json asset check a.example b.example c.example
+\`\`\`
+
+Markdown / CSV are also available for sharing in docs / chat:
+
+\`\`\`bash
+chainpatrol asset check phish.example --output markdown
+chainpatrol asset check a.example b.example --output csv
+\`\`\`
+
+If any individual lookup fails, the CLI still prints results for the
+successful ones, then exits non-zero so failures aren't silently
+swallowed.
+
+### \`asset types\` \u2014 List every supported asset type and what it means
+
+When a user asks "what is \`ARCHIVE_ORG\`?", "what does \`PAGE\` mean?",
+or "what asset types does ChainPatrol support?" \u2014 don't guess. Run:
+
+\`\`\`bash
+chainpatrol asset types
+chainpatrol --json asset types
+\`\`\`
+
+The mapping is bundled with the CLI (no API or auth required), so this
+is safe to run anywhere. Each row is \`{ type, label, description }\`:
+\`type\` is the canonical enum value used by every \`--asset-type\` flag
+(\`asset list\`, \`threats list\`, \`takedowns list\`, \`detections list\`,
+\`reports list\`, \`orgs assets list\`); \`label\` is the human-friendly
+display name (\`ARCHIVE_ORG\` \u2192 \`Archive.org\`, \`PAGE\` \u2192 \`Page\`,
+\`FIVE_HUNDRED_PX\` \u2192 \`500px\`); \`description\` is a one-line note for
+unobvious entries.
+
+Use this whenever you need to translate between enum and display name,
+validate that a type the user mentioned is real, or enumerate options
+before constructing a filter.
+
+### \`configs list\` \u2014 List detection configurations
+
+Requires authentication and an organization slug.
+
+\`\`\`bash
+chainpatrol configs list --org <slug>
+\`\`\`
+
+JSON mode:
+\`\`\`bash
+chainpatrol --json configs list --org <slug>
+\`\`\`
+
+The \`--org\` flag is saved for future commands. Once set, you can omit it:
+\`\`\`bash
+chainpatrol configs list
+\`\`\`
+
+### \`reports list\` \u2014 List recent reports for an organization
+
+Returns the most recent reports submitted for an organization. Each report
+includes a \`reportedByCustomer\` boolean indicating whether the report was
+submitted by a customer of ChainPatrol (e.g. via API key, Slack/Telegram bot,
+or another external integration) rather than by ChainPatrol's automated
+detections or staff reviewers.
+
+\`\`\`bash
+chainpatrol reports list --org <slug>
+\`\`\`
+
+Common flags:
+- \`--limit <n>\` page size (1-20)
+- \`--cursor <id>\` pagination cursor (use \`nextCursor\` from a previous response)
+- \`--status <s>\` filter by report status (e.g. \`TODO\`, \`IN_PROGRESS\`, \`DONE\`)
+- \`--search <q>\` search query across title/description/asset content
+- \`--reported-by-customer\` only show reports submitted by a customer
+- \`--no-reported-by-customer\` only show reports NOT submitted by a customer
+  (i.e. found by ChainPatrol's automation or staff)
+
+JSON mode is recommended when you want to analyze the data programmatically:
+\`\`\`bash
+chainpatrol --json reports list --org <slug> --reported-by-customer
+\`\`\`
+
+The response includes \`totalCount\`: the number of reports matching the same
+filters as the query, independent of \`--limit\`/\`--cursor\`. Use it to:
+- Report a denominator when sampling (e.g. "sampled 200 of ~4,235").
+- Decide up front whether to page through everything or narrow filters first \u2014
+  if \`totalCount\` is huge, add more filters instead of paginating blindly.
+- Drive a progress indicator while paginating with \`nextCursor\`.
+
+\`totalCount\` honors every list filter (\`--status\`, \`--reported-by-customer\` /
+\`--no-reported-by-customer\`, \`--exclude-automation\`, \`--review-status\` /
+\`--only-rejected\`, \`--asset-type\`, brand, \`--country-code\`, \`--from\`/\`--to\`,
+\`--updated-from\`/\`--updated-to\`, \`--search\`, \`--reporter-query\`), so changing
+filters changes the count. \`reports\` (the returned page) is capped by
+\`--limit\` (max 20); \`totalCount\` is not.
+
+#### Use case: finding gaps in ChainPatrol detection
+
+Customer-reported reports (\`reportedByCustomer=true\`) are a valuable signal
+for finding gaps in ChainPatrol's automated detections and staff triage: each
+one is a threat the customer found before ChainPatrol's own systems did. When
+the user asks something like:
+
+- "show me the threats our customers are reporting"
+- "what is X's customer reporting?"
+- "where are we missing detections for org Y?"
+- "summarize recent reports submitted by customers"
+
+\u2026use \`chainpatrol --json reports list --org <slug> --reported-by-customer\`
+to fetch them, then highlight patterns (asset types, domains, common
+keywords, recurring brands) so the user can:
+1. Spot detection coverage gaps to fix in the org's detection configs.
+2. Improve staff triage runbooks for recurring scams.
+3. Work directly with the customer to close the loop and prevent future
+   misses.
+
+You can also compare with the non-customer set using
+\`--no-reported-by-customer\` to gauge detection coverage on the same time
+window.
+
+### \`detections healthcheck\` \u2014 Validate enabled detection configs produce recent results
+
+Server-side check. The CLI calls the ChainPatrol API; the server fetches each
+enabled detection config for the org, counts results produced in the lookback
+window, and FAILs configs that fall under \`--min-results\` (or whose run
+errored when \`--run\` is set).
+
+\`\`\`bash
+chainpatrol --json detections healthcheck --org <slug>
+\`\`\`
+
+Flags:
+- \`--source <key>\` only validate one source (e.g. \`twitter_search\`)
+- \`--min-results <n>\` minimum results required in the window to pass
+- \`--lookback-hours <n>\` size of the lookback window
+- \`--run\` ask the server to run each config first, then validate the fresh output
+- \`--include-disabled\` also validate disabled configs
+
+What this command covers:
+- Configs that have gone silent (recentResultCount below threshold)
+- Configs that error when run (runOk=false) when \`--run\` is set
+
+What it does NOT cover:
+- Reviewing backlog / SLA breaches \u2192 use \`queues snapshot\`
+- Takedown ToDo / In Progress / Cancelled volumes \u2192 use \`queues snapshot\`
+- Spikes or drops in detection volume over time \u2192 use \`metrics breakdown\`
+- Customer-reported gaps \u2192 use \`reports list --reported-by-customer\`
+- Google Safe Browsing submission errors (not yet exposed in CLI)
+
+Use it as the first signal in the Detection part of an org healthcheck, then
+fall back to the manual checks in the HealthCheck Guide below for everything
+else.
+
+> Prefer the newer \`healthchecks\` namespace below. \`detections healthcheck\`
+> is the original single-purpose command; the \`healthchecks\` namespace is
+> the canonical place to discover and run every check we expose.
+
+### \`healthchecks list | run\` \u2014 Run uniform org healthchecks via the public API
+
+The \`healthchecks\` namespace is the canonical way to run the named checks
+from the Organization HealthCheck Guide below. Each implemented endpoint
+returns the same uniform shape \u2014 \`{ id, ok, severity, observed, threshold,
+findings, suggestedAction }\` \u2014 so the CLI / agent can render every check the
+same way regardless of category.
+
+\`\`\`bash
+# Discover every check the platform exposes today, including planned checks
+# that are not yet implemented on the backend.
+chainpatrol --json healthchecks list
+
+# Run a single named check.
+chainpatrol --json healthchecks run reviewing.backlog --org <slug>
+
+# Run every implemented check in parallel and aggregate the results.
+chainpatrol --json healthchecks run --all --org <slug>
+\`\`\`
+
+Each implemented check has a stable id of the form \`category.name\`. Implemented
+ids today: \`detections.silent-configs\`, \`reviewing.backlog\`,
+\`reviewing.old-proposals\`, \`reviewing.watchlist-backlog\`,
+\`reviewing.watchlist-old\`, \`takedowns.todo-volume\`,
+\`takedowns.in-progress-volume\`, \`takedowns.stale-in-progress\`,
+\`takedowns.cancelled-count\`, \`takedowns.automation-off\`,
+\`assets.dead-asset-spike\`.
+
+### Pending proposals: "Needs Review" vs "Watchlisted"
+
+PENDING proposals split into two operationally distinct buckets, and we
+grade them with separate checks:
+
+- **Needs Review** \u2014 pending proposals the reviewing UI shows by default
+  (\`excludeWatchlisted=true\`): assets that are NOT on a watchlist, OR
+  reports submitted by a customer (those stay visible even when the asset
+  is watchlisted). This is the actionable queue reviewers work from, so
+  pile-ups and old items here are high-priority signals (\`fail\` severity
+  is reachable).
+- **Watchlisted** \u2014 pending proposals on watchlisted assets (excluding
+  customer-reported reports). The reviewing UI hides these by default
+  because watchlisting is the act of intentionally deferring an asset.
+  Pile-ups and aged items here are worth surfacing as cleanup work, but
+  severity is **capped at warn** so they never block on the same SLA as
+  Needs Review. When reporting findings, treat these as lower-priority.
+
+Each healthcheck result includes an \`appUrl\` field (string or null) that
+deep-links to the relevant filtered admin page in the web app \u2014 e.g. the
+takedowns page filtered to IN_PROGRESS for \`takedowns.stale-in-progress\`,
+or the review page filtered to oldest pending for \`reviewing.old-proposals\`.
+**When reporting a non-OK healthcheck to the user, always surface the
+\`appUrl\` so they can jump straight to the right view.** Some checks
+(\`detections.silent-configs\`, \`assets.dead-asset-spike\`) emit \`null\`
+because no filterable list page exists for that signal yet.
+
+Implemented checks today:
+
+- **detections.silent-configs** \u2014 equivalent to \`detections healthcheck\`,
+  exposed under the uniform shape.
+- **reviewing.backlog** \u2014 counts Needs Review pending proposals and grades
+  severity against per-org thresholds (default warn=50, fail=100).
+- **reviewing.old-proposals** \u2014 counts Needs Review proposals older than
+  the warn / fail age thresholds (default 7 / 14 days) and lists the
+  oldest offenders.
+- **reviewing.watchlist-backlog** \u2014 counts watchlisted pending proposals
+  (default warn=200). Severity capped at warn.
+- **reviewing.watchlist-old** \u2014 counts watchlisted pending proposals older
+  than the warn-age threshold (default 30 days) and lists the oldest.
+  Severity capped at warn.
+- **takedowns.todo-volume** \u2014 counts takedowns in TODO (default warn=50,
+  fail=100). Pile-ups here usually mean an automation gap on a new threat
+  surface, or manual-filing capacity issues.
+- **takedowns.in-progress-volume** \u2014 counts takedowns currently IN_PROGRESS
+  regardless of age (default warn=30, fail=75). Complements
+  \`stale-in-progress\` \u2014 a high count signals vendor-side or
+  submission-format problems even before items go stale.
+- **takedowns.stale-in-progress** \u2014 counts takedowns sitting in IN_PROGRESS
+  past the staleness threshold (default 7 days) and lists the oldest.
+- **takedowns.cancelled-count** \u2014 counts CANCELLED transitions from the
+  TakedownEvent log over a rolling window (default 7d, warn=3, fail=10).
+  Cancellations should be rare; a spike usually means a proposal-funnel
+  quality problem or misuse of the CANCELLED status.
+- **takedowns.automation-off** \u2014 flags orgs with takedown service enabled
+  but \`isAutomatedTakedownsActive\` off for too long (default warn=30d,
+  fail=60d). Skipped for orgs with takedown service entirely disabled.
+- **assets.dead-asset-spike** \u2014 compares DEAD-detection events in the
+  current window against the prior baseline rate; warns on a multiplier
+  exceeding the threshold (default 24h vs 7d, \xD72 warn / \xD74 fail) once the
+  current count clears the \`minSpikeCount\` floor. Catches liveness-checker
+  regressions after platform changes.
+
+The following checks are listed by \`healthchecks list\` (\`implemented: false\`)
+but **not yet implemented on the backend** \u2014 when the agent surfaces them in
+a healthcheck report, mark them explicitly as "manual check, no API yet":
+
+- **detections.coverage-gaps** \u2014 blocked assets vs. enabled-source correlation.
+  Still requires manual reasoning with \`configs list\` + \`reports list\`.
+- **detections.spike** / **detections.drop** \u2014 require server-side baseline
+  modeling. Use \`metrics breakdown --by day\` as an interim signal.
+- **reviewing.auto-approval-spike** \u2014 needs distinguishing automation vs.
+  human approvers in the review history. Use \`metrics breakdown\` as a proxy.
+- **blocklisting.gsb-cancelled-rate** \u2014 Google Safe Browsing submission state
+  is not yet exposed in the public API.
+- **assets.dead-but-alive** / **assets.alive-but-marked-dead** \u2014 require live
+  HTTP probes against asset URLs, which is not a synchronous-healthcheck
+  shape. Until a dedicated probe command exists, sample a handful manually
+  from \`assets list --status DEAD\` (or ALIVE) and verify in a browser. Notify
+  ChainPatrol engineering if the liveness checker looks miscalibrated.
+
+When the user asks to "run a healthcheck on org X", the canonical command is:
+
+\`\`\`bash
+chainpatrol --json healthchecks run --all --org X
+\`\`\`
+
+This iterates the implemented entries in \`healthchecks list\`, runs them in
+parallel, and aggregates the uniform results. Combine with the manual checks
+in the HealthCheck Guide below for everything still marked
+\`implemented: false\`.
+
+### \`queues snapshot\` \u2014 Operations review/takedown queue snapshot
+
+Server-side aggregation of the operations review queue (pending proposals,
+SLA breaches, age buckets) and the takedown queue (open, in-progress, stale).
+
+\`\`\`bash
+chainpatrol --json queues snapshot --org <slug>
+\`\`\`
+
+Useful for the **Reviewing** and **Takedowns** sections of the HealthCheck
+Guide. Key signals in the response:
+- \`reviewQueue.totalPendingProposals\` and \`reviewQueue.distinctReports\` \u2014
+  backlog size
+- \`reviewQueue.slaBuckets.breached\` \u2014 SLA breaches (treat any breach as a
+  finding)
+- \`reviewQueue.ageBuckets.gte168h\` \u2014 proposals older than 7 days (anything
+  >14 days from the manual guide should always be in here)
+- \`takedownQueue.totalOpen\` and \`takedownQueue.staleInProgress\` \u2014 open
+  and stuck takedowns
+
+Use \`--all\` to snapshot every org you have access to instead of a single slug.
+
+### \`orgs list\` \u2014 List organizations with subscription status, service toggles, and admin-approval scope
+
+Returns every organization the caller can see, with each org's
+subscription status (\`PROSPECT\`, \`TRIAL\`, \`ACTIVE\`, \`INTEGRATION\`),
+which services are active, and the per-org "Obligatory Organization
+Admin Approval" toggle (with its asset-type scope). Use it to answer
+questions like "which customers have takedowns enabled but automation
+off?", "which prospects don't have detection turned on yet?", or "which
+orgs require admin approval before adding Twitter assets to the
+blocklist?" \u2014 filters compose with AND and are applied server-side, so
+one call returns the final list.
+
+\`\`\`bash
+chainpatrol --json orgs list \\
+  --subscription-status ACTIVE \\
+  --service-active takedowns \\
+  --service-manual takedowns
+\`\`\`
+
+#### Per-service response shape \u2014 \`automated\` is takedowns-only
+
+Every service exposes an \`active\` boolean. **Only \`takedowns\`
+additionally exposes \`automated\`** \u2014 that is the one service where the
+manual-vs-automated distinction changes real platform behavior (whether
+ChainPatrol files the takedown on its own, or queues it for a human to
+file). \`reporting\`, \`reviewing\`, and \`protection\` have backing
+\`isAutomated*Active\` columns in the database, but those flags have no
+operational effect today, so the API deliberately omits them from both
+the response and the \`services\` filter \u2014 surfacing them would invite
+misleading filters like "reporting.automated=true" that don't mean
+anything. \`detection\` and \`darkWebMonitoring\` have always been
+single-flag services.
+
+#### Obligatory Organization Admin Approval
+
+Each org also has a separate "Obligatory Organization Admin Approval"
+toggle (\`Organization.requiresCustomerReview\` in the schema, surfaced
+on the Services settings page in the app) that gates customer-side
+review of proposals ChainPatrol staff have already approved before
+they're added to the blocklist. It is NOT one of the operational
+services above \u2014 it is an org-policy toggle with its own per-asset-type
+scope.
+
+Each org's response includes:
+
+\`\`\`json
+{
+  "obligatoryAdminApproval": {
+    "active": true,
+    "assetTypes": ["TWITTER", "URL"]
+  }
+}
+\`\`\`
+
+- \`active=true\` + empty \`assetTypes\` means approval applies to
+  **all** asset types \u2014 the org has not narrowed the scope.
+- \`active=true\` + a non-empty \`assetTypes\` list means approval is
+  required only for those asset types.
+- \`active=false\` means no approval is required; \`assetTypes\` is
+  always empty in that case.
+
+So per-org JSON looks like:
+
+\`\`\`json
+{
+  "services": {
+    "reporting":         { "active": true },
+    "reviewing":         { "active": true },
+    "protection":        { "active": false },
+    "takedowns":         { "active": true, "automated": false },
+    "detection":         { "active": true },
+    "darkWebMonitoring": { "active": false }
+  },
+  "obligatoryAdminApproval": { "active": true, "assetTypes": ["TWITTER"] },
+  "pendingServiceApprovals": [
+    {
+      "service": "protection",
+      "automated": false,
+      "serviceType": "isProtectionActive",
+      "serviceName": "Wallet Blocking",
+      "requestedAt": "2026-05-30T18:04:11.000Z"
+    }
+  ]
+}
+\`\`\`
+
+#### Pending service approvals (Wallet Blocking / Takedowns)
+
+Turning on **Wallet Blocking** (\`protection\`, the "is protection active"
+toggle) or **Takedowns** is approval-gated: when a lower-level org member
+tries to enable one, ChainPatrol records a pending request that a higher-up
+at the org \u2014 an org OWNER, or ChainPatrol staff acting as owner \u2014 must
+approve before the service actually turns on. \`pendingServiceApprovals\`
+lists those open, awaiting-sign-off requests per org.
+
+This is the answer to "which organizations have a pending approval for
+Wallet blocking or Takedown services?" \u2014 it is NOT the same as "which orgs
+have Wallet Blocking turned off". An org can have \`protection.active=false\`
+with **no** pending approval (nobody has asked) OR **with** a pending
+approval (someone asked and it's waiting on an owner). Only
+\`pendingServiceApprovals\` distinguishes the two.
+
+Each entry:
+
+- \`service\` \u2014 \`protection\` (Wallet Blocking) or \`takedowns\`, matching the
+  \`services\` keys.
+- \`automated\` \u2014 \`true\` when the request is for the automated variant
+  (e.g. "Automated Wallet Blocking").
+- \`serviceType\` \u2014 raw enum, e.g. \`isProtectionActive\`.
+- \`serviceName\` \u2014 human label, e.g. \`Wallet Blocking\`.
+- \`requestedAt\` \u2014 when the enable request was submitted (ISO 8601, UTC).
+
+An **empty array means nothing is awaiting approval** \u2014 read \`services\` for
+the current on/off state, never infer it from this field.
+
+When a user asks about "automated reporting / reviewing / protection",
+explain that the flag exists in the DB but has no operational effect and
+isn't exposed by the public API \u2014 only \`takedowns.automated\` carries a
+real meaning.
+
+Filter flags (all optional, all comma-separated lists where noted):
+
+- \`--query <text>\` partial name match (substring, case-insensitive)
+- \`--subscription-status <list>\` one or more of \`PROSPECT\`, \`TRIAL\`,
+  \`ACTIVE\`, \`INTEGRATION\`. \`INACTIVE\` is intentionally not reachable
+  through this filter \u2014 \`orgs list\` only ever returns live customers.
+- \`--service-active <list>\` services that must be active
+- \`--service-inactive <list>\` services that must be inactive
+- \`--service-automated <list>\` services whose automation must be ON.
+  **Only \`takedowns\` is accepted** \u2014 the other services don't have a
+  meaningful automation toggle. Passing any other service name errors out.
+- \`--service-manual <list>\` services whose automation must be OFF.
+  Same restriction \u2014 only \`takedowns\`.
+- \`--obligatory-approval-active\` \u2014 only orgs with admin approval on
+- \`--obligatory-approval-inactive\` \u2014 only orgs with admin approval off
+- \`--obligatory-approval-asset-type <list>\` \u2014 only orgs whose admin
+  approval scope covers EVERY listed asset type. The match treats an
+  org's empty per-asset-type list as "applies to all asset types", so a
+  fully-broad org matches every value passed here. Passing this flag
+  implies the feature is on, so it can't be combined with
+  \`--obligatory-approval-inactive\`. Use the canonical asset-type enum
+  names (\`TWITTER\`, \`URL\`, \`PAGE\`, \u2026); run \`chainpatrol asset types\`
+  to see them all.
+- \`--pending-approval-active\` \u2014 only orgs with at least one open
+  service-enable approval awaiting a higher-up's sign-off.
+- \`--pending-approval-inactive\` \u2014 only orgs with no pending approvals.
+- \`--pending-approval-service <list>\` \u2014 only orgs with a pending approval
+  for one of the listed services. Accepts \`protection\` (Wallet Blocking)
+  and/or \`takedowns\` \u2014 those are the only approval-gated services.
+  Matches both the manual and automated variant. Passing this flag implies
+  a pending approval exists, so it can't be combined with
+  \`--pending-approval-inactive\`.
+
+Service names: \`reporting\`, \`reviewing\`, \`protection\`, \`takedowns\`,
+\`detection\`, \`darkWebMonitoring\`.
+
+Customers see only orgs they're a member of. Staff/superuser sessions see
+every matching org. The response is the same in both cases; visibility is
+enforced server-side.
+
+#### Use case: finding which orgs require admin approval for an asset type
+
+When a user asks "which orgs require admin approval before blocking
+Twitter assets?", reach straight for the filter \u2014 no client-side
+post-processing needed:
+
+\`\`\`bash
+chainpatrol --json orgs list --obligatory-approval-asset-type TWITTER
+\`\`\`
+
+To audit just the broad opt-ins ("which orgs require approval for
+everything?"), filter on the toggle and inspect \`assetTypes\` in the
+output \u2014 an empty array means "all":
+
+\`\`\`bash
+chainpatrol --json orgs list --obligatory-approval-active \\
+  | jq '.organizations[] | select(.obligatoryAdminApproval.assetTypes | length == 0) | .slug'
+\`\`\`
+
+#### Use case: tracking orgs with a pending Wallet Blocking / Takedown approval
+
+When a user asks "which organizations have a pending approval for Wallet
+blocking or Takedown services?", do NOT reach for \`--service-inactive
+protection\` \u2014 that lists orgs with the service turned OFF, which is a
+different question. Use the pending-approval filter, which surfaces
+staff-initiated enable requests still waiting on a higher-up:
+
+\`\`\`bash
+# Every org with a pending Wallet Blocking OR Takedown approval:
+chainpatrol --json orgs list --pending-approval-service protection,takedowns
+
+# Just Wallet Blocking:
+chainpatrol --json orgs list --pending-approval-service protection
+
+# Any pending approval at all, then read each org's pendingServiceApprovals:
+chainpatrol --json orgs list --pending-approval-active \\
+  | jq '.organizations[] | {slug, pending: [.pendingServiceApprovals[].serviceName]}'
+\`\`\`
+
+### \`orgs get\` \u2014 Get a single organization by slug
+
+Look up one organization the caller has access to. Returns the same per-org
+shape as a single row from \`orgs list\` \u2014 \`active\` for every service,
+plus \`automated\` on \`takedowns\` only (see the note above on why other
+services don't expose an automation flag), plus \`obligatoryAdminApproval\`
+(\`active\` + \`assetTypes\`) and \`pendingServiceApprovals\` (open Wallet
+Blocking / Takedown enable requests awaiting a higher-up's sign-off).
+Anything you could read from \`orgs list\` you can also read here without
+paging or filtering. Use it when the user names a specific customer ("show
+me acme's setup", "is takedowns automation on for morpho?", "does this org
+require admin approval for Twitter?", "is morpho waiting on a Wallet
+Blocking approval?") and you don't need the rest of the catalogue.
+
+\`\`\`bash
+chainpatrol orgs get <slug>
+chainpatrol --json orgs get <slug>
+\`\`\`
+
+Permission rules match \`orgs list\`:
+
+- Org-scoped API keys: must match the slug \u2014 querying another org returns
+  403.
+- User sessions / user-scoped API keys: need an active OrganizationMembership
+  on the slug. Staff/superusers can read any org.
+- Soft-deleted orgs are not returned (404). A 404 also fires for orgs the
+  caller would not be authorized to see \u2014 the endpoint deliberately does
+  not distinguish "doesn't exist" from "you can't see this" beyond the
+  generic 403/404 envelope.
+
+Prefer \`orgs get\` over \`orgs list\` + client-side filter whenever the
+caller already knows the slug; it's one round-trip and side-steps the
+list filters entirely.
+
+#### Use case: finding service configuration gaps across the customer base
+
+When the user asks something like "which customers are paying us but don't
+have takedowns automated yet?" or "any orgs running detection without
+takedowns?", reach for \`orgs list\` \u2014 it's the only command that exposes
+service flags across multiple orgs in one call. Run it in \`--json\` mode
+and summarize patterns by service or by subscription tier.
+
+### \`brands list\` \u2014 List the brands (sub-brands) belonging to an org
+
+Returns every brand for the org the caller is authenticated as, both
+parent / product brands (\`type: "ORGANIZATION"\`) and individual /
+employee brands (\`type: "INDIVIDUAL"\`). Soft-deleted brands are excluded.
+The endpoint is org-scoped and inferred from auth \u2014 there's no \`--org\`
+flag \u2014 so org-scoped API keys, user API keys, and user sessions all work
+without extra arguments.
+
+\`\`\`bash
+chainpatrol brands list                          # all brands
+chainpatrol brands list --type INDIVIDUAL        # employee / person brands only
+chainpatrol brands list --type ORGANIZATION      # product / parent brands only
+chainpatrol --json brands list                   # machine-readable
+\`\`\`
+
+Each entry has \`{ id, slug, name, type, description, brandGroupId, createdAt }\`.
+Use this when you need to:
+
+- Distinguish employee vs. product brands ahead of time \u2014 e.g. while
+  running a trend search and you want to highlight which spiking
+  sub-brands are employees so the user gets a direct heads-up to the
+  person involved.
+- Resolve a brand name the user mentions to its \`slug\` for use with
+  \`metrics organization --brand-slug <slug>\` or as a \`brandId\` for
+  \`takedowns list --brand <id>\`.
+- Audit a customer's setup \u2014 "how many employee brands does this org
+  protect?" or "are there brands the org set up but never wired into a
+  detection config?"
+
+### \`metrics summary | found | breakdown | organization\` \u2014 Org metrics for spike/drop analysis
+
+#### Decision rule \u2014 read this before picking a metrics subcommand
+
+When the user asks for a number that **spans more than one customer/org/brand**
+\u2014 phrases like "across all clients", "across all customers", "across all orgs",
+"across all brands", "company-wide", "total takedowns", "total threats",
+"average takedowns per day across customers", "rollup across customers",
+"how many takedowns in the last 7 days?" (no org named) \u2014 the answer is
+**\`chainpatrol metrics organization --all-my-orgs\`** (or \`--slugs\`
+if you want a specific subset). \`summary\`, \`found\`, and \`breakdown\`
+are single-org commands and have **no** \`--slugs\`/\`--all-my-orgs\`
+form; only \`organization\` does. The multi-org form rolls totals +
+per-day / per-org-per-day averages + a per-org breakdown server-side
+in **one** HTTP call.
+
+**Anti-patterns to avoid:**
+
+- \u274C "There's no cross-org aggregation in the CLI." There is \u2014
+  \`metrics organization --all-my-orgs\` (or \`--slugs\`). Don't bail
+  out citing the docs without trying these flags.
+- \u274C Looping \`metrics summary --org X\` once per customer to sum
+  client-side. The multi-org form is one round-trip; the loop is what
+  made the endpoint 503-prone in the first place.
+- \u274C Calling \`orgs list\` to build a slug list when you just want
+  "everything." Use \`--all-my-orgs\` and skip the enumeration entirely \u2014
+  the server resolves the same set via shared logic. Save \`orgs list\`
+  +  \`--slugs\` for cases where the user asked for a specific subset.
+- \u274C Routing the user to Metabase / the data warehouse for a question
+  the CLI can answer. Reach for Metabase only when the metric isn't
+  in the \`--include\` list (\`reports\`, \`newThreats\`,
+  \`threatsWatchlisted\`, \`takedownsFiled\`, \`takedownsCompleted\`,
+  \`domainThreats\`, \`twitterThreats\`, \`telegramThreats\`,
+  \`otherThreats\`, \`blockedByType\`, \`blockedByDay\`).
+- \u274C "Iterating 100+ orgs one-by-one isn't practical here." Right \u2014
+  that's why you don't iterate. \`--all-my-orgs\` covers up to 500
+  orgs in a single call; for larger fleets, narrow with
+  \`--subscription-status\` / \`--service-active\`, or split an
+  explicit \`--slugs\` list into batches and sum.
+
+#### Common cross-org recipe (copy and run)
+
+The shortest answer to "how many takedowns across all customers in the
+last 7 days?" is a single call \u2014 no \`orgs list\` step needed:
+
+\`\`\`bash
+chainpatrol --json metrics organization \\
+  --all-my-orgs \\
+  --subscription-status ACTIVE \\
+  --service-active takedowns \\
+  --include takedownsCompleted \\
+  --from <YYYY-MM-DD 7 days ago> --to <YYYY-MM-DD today>
+
+# Read these fields from the JSON:
+#   .scope.orgs                                    \u2190 which orgs the server resolved
+#   .metrics.takedownsCompleted                    \u2190 grand total across all orgs
+#   .averages.perDay.takedownsCompleted            \u2190 total / windowDays
+#   .averages.perOrgPerDay.takedownsCompleted      \u2190 total / numOrgs / windowDays
+#   .perOrg[slug].metrics.takedownsCompleted       \u2190 per-customer breakdown
+\`\`\`
+
+Replace \`takedownsCompleted\` with whatever metric the user asked about.
+Replace the date range with whatever window they asked about (default
+3 months if they didn't say).
+
+If the user *asked* for a specific subset of customers ("how many for
+acme, beta, gamma combined?"), use \`--slugs acme,beta,gamma\` instead
+of \`--all-my-orgs\`. \`--slugs\` accepts up to 500 entries.
+
+**Auth note for \`--all-my-orgs\`:** requires a user session or a
+user-scoped API key (it inherits your memberships). Org-scoped API
+keys are rejected \u2014 they're pinned to a single org by design. If
+\`whoami\` shows an org-scoped key, use a Bearer session instead or
+ask the user to provision a user API key.
+
+#### Single-org examples
+
+\`\`\`bash
+chainpatrol --json metrics summary      --org <slug>                                  # defaults to last 3 months
+chainpatrol --json metrics summary      --org <slug> --this-week
+chainpatrol --json metrics breakdown    --org <slug> --by day --this-week
+chainpatrol --json metrics found        --org <slug> --from <YYYY-MM-DD> --to <YYYY-MM-DD>
+chainpatrol --json metrics organization --org <slug>                                  # defaults to last 3 months
+\`\`\`
+
+**Always operate on a bounded window.** When no \`--from\`/\`--to\`/\`--this-week\`
+is passed, every metrics subcommand defaults to the trailing **last 3 months**
+ending now. The default exists because unbounded org-wide aggregates over
+multi-year history routinely time out at the platform layer (Vercel's
+30s function cap), which surfaces to clients as a 503. Stick to the default,
+or pass an explicit narrower window \u2014 don't try to bypass the default by
+guessing wide \`--from\` values.
+
+The resolved range is echoed back in every output format so the user can
+see exactly what they got:
+
+- JSON: \`{ "range": { "startDate": "...", "endDate": "...", "label": "last 3 months" } }\`
+- Markdown / human: the header line includes the label, e.g.
+  \`Organization metrics for acme \u2014 last 3 months\`, followed by
+  \`Range: <startDate> \u2192 <endDate>\`.
+
+When reporting numbers to the user (especially averages and rates),
+**state the window explicitly** \u2014 say "averaged over the last 3 months"
+rather than just quoting a number, since the same prompt phrased
+differently can pick a different window.
+
+\`breakdown\` is the one you usually want for healthchecks: it returns a
+time series (by day or week) of reports, new threats, watchlisted threats,
+and takedowns filed/completed. Compare the latest period against a prior
+window to spot the **spike** or **drop** signals described in the manual
+HealthCheck Guide. \`summary\` returns a single window total; \`found\` is
+oriented around when threats were first discovered; \`organization\` is
+the full customer-facing dashboard slice (reports, new threats,
+watchlisted, takedowns filed/completed, plus per-type and per-day
+breakdowns).
+
+#### \`--include\` \u2014 only compute the metrics you actually need
+
+\`metrics organization\` runs one Prisma aggregate per requested field.
+By default all 11 are computed in parallel. Pass \`--include\` (or
+\`include: [\u2026]\` in the JSON body) with the comma-separated subset you
+care about to skip the rest \u2014 the unrequested fields come back as
+\`null\` instead of a number, and the server never runs those queries:
+
+\`\`\`bash
+# Only takedowns \u2014 one of the cheap shapes
+chainpatrol --json metrics organization --org <slug> \\
+  --include takedownsFiled,takedownsCompleted
+
+# Time series only, no scalar counts
+chainpatrol --json metrics organization --org <slug> --include blockedByDay
+\`\`\`
+
+Allowed values: \`reports\`, \`newThreats\`, \`threatsWatchlisted\`,
+\`takedownsFiled\`, \`takedownsCompleted\`, \`domainThreats\`,
+\`twitterThreats\`, \`telegramThreats\`, \`otherThreats\`,
+\`blockedByType\`, \`blockedByDay\`.
+
+Use this whenever the user's question is specific ("how many takedowns
+did we file last month?"). It is the lowest-effort way to make a
+metrics call cheap enough to run repeatedly. Pair it with an explicit
+date window for the best behavior.
+
+#### \`--slugs\` \u2014 multi-org rollups in one call (use this for "across all customers/clients")
+
+When the user asks for a total or an average **across more than one
+org** \u2014 e.g. "how many takedowns did we complete across all clients
+in the last 7 days?", "average reports per org per day this month",
+"top 5 customers by new threats" \u2014 reach for \`--slugs\` instead of
+looping. The server fans out the per-org aggregates internally,
+sums into totals, computes per-day and per-org-per-day averages,
+and returns a per-org breakdown in a **single HTTP round trip**:
+
+\`\`\`bash
+# Total takedowns completed across three customers, last 7 days
+chainpatrol --json metrics organization \\
+  --slugs acme,beta,gamma \\
+  --include takedownsCompleted \\
+  --from 2026-05-12 --to 2026-05-19
+\`\`\`
+
+The response shape switches to multi-org:
+
+\`\`\`json
+{
+  "scope": { "mode": "multi", "orgs": ["acme", "beta", "gamma"] },
+  "metrics":   { "takedownsCompleted": 117, ... },       // sum across orgs
+  "averages": {
+    "perDay":       { "takedownsCompleted": 16.71, ... },  // total / windowDays
+    "perOrgPerDay": { "takedownsCompleted": 5.57, ... },   // total / numOrgs / windowDays
+    "windowDays": 7
+  },
+  "perOrg": { "acme": { "metrics": { ... } }, "beta": { ... }, "gamma": { ... } }
+}
+\`\`\`
+
+To answer **"across all of our customers"**, prefer \`--all-my-orgs\` \u2014
+it lets the server resolve the org set in one round-trip, no \`orgs
+list\` step needed:
+
+\`\`\`bash
+chainpatrol --json metrics organization \\
+  --all-my-orgs \\
+  --subscription-status ACTIVE \\
+  --service-active takedowns \\
+  --include takedownsCompleted \\
+  --from 2026-05-12 --to 2026-05-19
+\`\`\`
+
+Use \`--slugs <comma-list>\` only when the user asked for a *specific*
+subset of customers ("how many for acme, beta, gamma combined?"); the
+two flags are mutually exclusive. Both forms cap at 500 orgs per call;
+if a real fleet exceeds that, narrow with
+\`--subscription-status\`/\`--service-active\` filters or split an
+explicit \`--slugs\` list into batches and sum. **Do not loop
+\`metrics organization\` once per org** \u2014 N HTTP round-trips is what
+made the old code 503.
+
+Always pair the multi-org form with \`--include\` to narrow the metric
+set to what the user actually asked about. "How many takedowns did
+we complete?" \u2192 \`--include takedownsCompleted\`; "average reports
+per day per customer?" \u2192 \`--include reports\`. Skipping \`--include\`
+runs ~11 aggregates per org which is rarely necessary.
+
+#### Auth: which credential can use \`--slugs\` / \`--all-my-orgs\`
+
+- **Org-scoped API key** (the most common production key): can only
+  query its own org. If \`--slugs\` contains foreign orgs the server
+  returns 403; \`--all-my-orgs\` is also rejected. Use the \`--org\`
+  form (or omit both) instead.
+- **User API key**: inherits the user's org memberships, so it can
+  query any org the user is a member of (or any org for staff
+  users) via \`--slugs\` or \`--all-my-orgs\`. This is the credential
+  you want for cross-org rollups from automated agents.
+- **Session auth** (Bearer token, e.g. \`chainpatrol login\`): same
+  membership rules as the user. Staff users can query any org.
+
+#### Reporting numbers to the user
+
+Whatever window and scope you choose, **make both explicit in your
+reply** \u2014 say "averaged across 12 customers over the last 3 months"
+or "summed across all paying orgs for the last 7 days." The same
+prompt phrased slightly differently can pick a different window or
+org set, and the response already echoes
+\`scope.mode\` / \`scope.orgs\` / \`averages.windowDays\` /
+\`range.label\` so you don't have to guess.
+
+### \`presets list | run\` \u2014 Packaged workflows for common jobs
+
+\`\`\`bash
+chainpatrol presets list
+chainpatrol presets run cs-weekly-health --org <slug>
+\`\`\`
+
+Use \`presets list\` to discover packaged multi-step workflows. The bundled
+\`cs-weekly-health\` preset runs the standard customer-success weekly health
+sweep; prefer it over hand-rolling the same sequence of commands.
+
+## Headless / agent-mode tips
+
+When running these commands from an agent or CI:
+
+- Prefer \`--json\` (or \`--output json\`) so output is structured and the
+  update-check stderr nudge is suppressed automatically.
+- Pass \`--no-input\` to forbid any interactive prompt (the CLI will error
+  out instead of waiting on a TTY).
+- Pass \`--no-color\` or set \`NO_COLOR=1\` if your sink can't render ANSI.
+- Set \`CHAINPATROL_NO_UPDATE_CHECK=1\` to silence the skill/npm freshness
+  nudge entirely.
+- For \`login\` specifically, see the headless runbook in the login section
+  above \u2014 login is the one command that needs background + tail handling.
+
+## Checking Auth Status
+
+To check if the user is logged in, read the credentials file:
+
+\`\`\`bash
+cat ~/.chainpatrol/credentials.json 2>/dev/null && echo "Logged in" || echo "Not logged in"
+\`\`\`
+
+Or start the login flow which will detect existing sessions:
+\`\`\`bash
+chainpatrol --json login
+\`\`\`
+
+## Configuration
+
+Config is stored at \`~/.chainpatrol/config.json\`:
+- \`apiUrl\` \u2014 API base URL (default: \`https://app.chainpatrol.io\`)
+- \`defaultOrg\` \u2014 Saved organization slug
+
+Override config dir with \`CHAINPATROL_CONFIG_DIR\` env var.
+
+## Version Checks
+
+The CLI runs two lightweight version checks alongside each command and prints
+a nudge to stderr if anything is out of date:
+
+- **Skill freshness**: compares the installed skill (\`~/.claude/skills/chainpatrol/SKILL.md\`)
+  to the version bundled with the CLI. If it's missing or older, the user is
+  asked to run \`chainpatrol setup\`.
+- **NPM freshness**: compares the running CLI version to the latest published
+  on the npm registry. The check is throttled to once per 24 hours and capped
+  at a 1.5s timeout, with the result cached at \`<configDir>/version-check.json\`.
+
+Set \`CHAINPATROL_NO_UPDATE_CHECK=1\` to silence both checks. JSON mode
+(\`--json\`) and quiet mode (\`-q\` / \`--quiet\`) also suppress the nudges so
+machine-readable output is never polluted.
+
+## Global Flags
+
+| Flag             | Description                                            |
+|------------------|--------------------------------------------------------|
+| \`--json\`         | Machine-readable JSON output (shortcut for \`--output json\`) |
+| \`--output <fmt>\` | Output format: \`human\` (default), \`json\`, \`markdown\`, \`csv\` |
+| \`--quiet\`, \`-q\`  | Suppress non-essential output and the update-check nudge |
+| \`--no-color\`     | Disable ANSI colors (also respects the \`NO_COLOR\` env var) |
+| \`--no-input\`     | Disable interactive prompts (use in scripts and agents) |
+| \`--org <slug>\`   | Organization slug (saved as the default for later commands) |
+| \`--help\`, \`-h\`   | Show help                                              |
+| \`--version\`      | Show version                                           |
+
+## Workflow
+
+When the user asks to use the CLI, follow this order:
+
+1. **Check login status** \u2014 Read \`~/.chainpatrol/credentials.json\` to see if they're logged in
+2. **Login if needed** \u2014 Run the login command and guide them through the device code flow
+3. **Set org if needed** \u2014 Ensure \`--org\` is provided or already saved in config
+4. **Run the requested command** \u2014 Execute the CLI command and show results
+
+## Detection Config Output
+
+The \`configs list\` command shows detection sources grouped by:
+- **Configured** \u2014 Sources with org-level configs (enabled/disabled with details)
+- **Global** \u2014 Sources that run globally for all orgs (CERTSTREAM, ASSET_CHECK, BLOCKLIST, etc.)
+- **Not Configured** \u2014 Sources available but not yet set up for the org
+
+Each config entry includes: title, status, cron schedule, and configuration parameters.
+
+## Organization HealthCheck Guide
+
+This guide explains how to look for things that may be wrong for a given org
+across the full pipeline: **detection \u2192 reviewing \u2192 blocklisting \u2192 takedowns**.
+When the user asks for a "health check", "audit", "what's wrong with org X",
+"review org X's setup", or similar, walk through each section below and surface
+findings.
+
+In each section there are things you can look for that may be wrong. Some
+checks have a dedicated CLI command that does most of the work server-side;
+others are soft / qualitative signals that still need you to fetch data with
+\`configs list\` or \`reports list\` and reason about it manually.
+
+### Quick Path: CLI commands that automate parts of this guide
+
+The canonical first step is now the \`healthchecks\` namespace, which runs
+every implemented check via the public API and returns a uniform shape per
+check (\`id\`, \`severity\`, \`observed\`, \`threshold\`, \`findings\`,
+\`suggestedAction\`):
+
+\`\`\`bash
+# Discover every check the platform exposes, implemented or planned.
+chainpatrol --json healthchecks list
+
+# Run every implemented healthcheck in parallel and aggregate the results.
+chainpatrol --json healthchecks run --all --org <slug>
+
+# Run a single named check.
+chainpatrol --json healthchecks run reviewing.backlog --org <slug>
+\`\`\`
+
+After \`healthchecks run --all\`, use these complementary commands to cover
+the signals that are not yet exposed as a uniform healthcheck endpoint:
+
+\`\`\`bash
+# Spikes / drops in detection volume over time (compare windows)
+chainpatrol --json metrics breakdown --org <slug> --by day --this-week
+
+# Customer-reported threats \u2014 gaps in our own detection
+chainpatrol --json reports list --org <slug> --reported-by-customer
+
+# What's enabled vs disabled vs not configured for the org
+chainpatrol --json configs list --org <slug>
+
+# Snapshot of review/takedown queues \u2014 raw counts behind several healthchecks
+chainpatrol --json queues snapshot --org <slug>
+
+# Packaged weekly customer-success sweep (preferred when it covers the ask)
+chainpatrol presets run cs-weekly-health --org <slug>
+\`\`\`
+
+Treat each command's output as one input to the healthcheck. The manual
+checks below still apply \u2014 especially for signals the CLI cannot infer on
+its own (e.g. "lots of Twitter assets are blocked but Twitter Post Search
+is disabled", or "this drop is fine because the config isn't relevant
+to this org"). Each subsection of the guide notes whether a healthcheck
+endpoint exists today and what to fall back on when it doesn't.
+
+### Reporting progress while running a healthcheck
+
+When the user asks for a healthcheck, narrate each step in real time so they
+can watch the run unfold. Do NOT batch results and dump everything at the
+end. For every check you run (Quick Path CLI command, or a manual signal
+where you're fetching data with \`configs list\` / \`reports list\` to
+reason about):
+
+1. **Before** you call the command, emit ONE short sentence stating what
+   you're about to check, including the org slug. Examples:
+   - "Running detection config healthcheck for morpho\u2026"
+   - "Snapshotting review and takedown queues for morpho\u2026"
+   - "Fetching customer-reported reports for morpho to look for detection gaps\u2026"
+
+2. **As soon as** the command returns, emit ONE short result line that
+   starts with a status word and ends with a key number or finding:
+   - \`DONE\` \u2014 ran cleanly, nothing to flag
+   - \`WARN\` \u2014 soft signal worth surfacing (e.g. a borderline backlog,
+     mild spike or drop, a config you'd want a human to confirm)
+   - \`FAIL\` \u2014 concrete failure that the user should act on
+   - Examples:
+     - "DONE \u2014 14/14 detection configs passing."
+     - "WARN \u2014 23 proposals in the review queue; 4 are older than 7 days."
+     - "FAIL \u2014 twitter_post_search returned 0 results in the last 24h with --run."
+
+3. Run **independent** checks in **parallel** (single message, multiple
+   Bash tool calls) so progress lines arrive quickly. \`detections
+   healthcheck\`, \`queues snapshot\`, \`metrics breakdown\`,
+   \`reports list --reported-by-customer\`, and \`configs list\` are all
+   independent of each other and safe to fire concurrently. Dependent
+   follow-ups (e.g. paginating \`reports list\` with a returned cursor,
+   or fetching extra detail on a single failing config) run after the
+   first round.
+
+4. After every check is reported, emit a short final **Summary** section:
+   - A one-line status per check (\u2713 / \u26A0 / \u2717 + name + key number).
+   - A short "Top issues" list of the highest-priority FAIL / WARN
+     findings, in priority order, with the concrete next action for each.
+
+Keep each progress line to one sentence. The goal is for the user to see
+the healthcheck happening, not to read a wall of text mid-run \u2014 full
+detail belongs in the final Summary or in a follow-up when the user asks
+about a specific finding.
+
+### Detection
+
+#### Enable Config That May Be Turned Off for Current Threats
+
+Blocked threats exist in an asset type but the matching detection source is
+turned off. For example: lots of Twitter assets are on the blocklist, but
+detection sources like "Twitter / X User Search" or "Twitter Post Search" are
+disabled. Those should be turned on.
+
+**Run via CLI:** **Not yet implemented as a healthcheck endpoint.** Listed in
+\`healthchecks list\` as \`detections.coverage-gaps\` with
+\`implemented: false\` \u2014 when reporting this signal in a healthcheck, note
+"manual check, no API yet". Until the endpoint lands, do the correlation
+manually: \`chainpatrol --json configs list --org <slug>\` for enabled vs
+disabled configs, then \`chainpatrol --json reports list --org <slug>\` for
+recent blocked-item asset types. Flag any asset type where blocked items
+exist but the matching detection source has \`status: "disabled"\` (or
+appears in the "Not configured" group).
+
+#### Spike in Detections
+
+A spike in recent detections is worth investigating. It could be a bad config
+change, or it could be a legitimate new attack push in this area \u2014 useful
+intel to surface to the security team as a targeted spike.
+
+**Run via CLI:** **Not yet implemented as a healthcheck endpoint.** Listed
+in \`healthchecks list\` as \`detections.spike\` with \`implemented: false\`.
+Until the endpoint lands, use \`chainpatrol --json metrics breakdown --org <slug> --by day --this-week\`
+(and a comparison window via \`--from\`/\`--to\`) to see daily detection
+volume. Anything notably above the recent baseline is a spike \u2014 cross-reference
+against recent config changes for that source.
+
+#### Drop in Detections
+
+A drop is also worth looking into. It may be a bad config change, or it may
+mean the config is not really relevant and can be safely turned off (not all
+default-on configs are relevant to every org).
+
+**Run via CLI:** the extreme case ("this source went silent") is covered
+today by \`chainpatrol --json healthchecks run detections.silent-configs --org <slug>\`,
+which is the canonical replacement for the older \`detections healthcheck\`.
+It fails any config whose \`recentResultCount\` is below \`--min-results\`
+in the \`--lookback-hours\` window; pass \`--run\` (via the lower-level
+\`detections healthcheck --run\`) to also catch configs that error when
+executed. For soft drops (still producing results but below baseline),
+\`detections.drop\` is marked \`implemented: false\` in \`healthchecks list\`
+\u2014 use \`metrics breakdown --by day\` and compare windows manually.
+
+### Reviewing
+
+PENDING proposals split into two operationally distinct buckets:
+
+- **Needs Review** \u2014 assets not on a watchlist, or reports submitted by a
+  customer. This is the reviewing UI's default view (\`excludeWatchlisted=true\`)
+  and the actionable queue reviewers work from. Pile-ups and aged items
+  here are high priority \u2014 \`fail\` severity is reachable.
+- **Watchlisted** \u2014 pending proposals on watchlisted assets (excluding
+  customer-reported reports). The UI hides these by default because
+  watchlisting is the act of intentionally deferring the asset. Pile-ups
+  and aged items here are worth surfacing as cleanup work but **severity
+  is capped at warn** \u2014 they should never block on the same SLA as Needs
+  Review.
+
+Each bucket has its own pile-up and age check, so you can grade them
+independently and tune thresholds without one drowning the other.
+
+#### Pile Up / Backlog of Needs-Review Proposals
+
+Too many proposals waiting in review. For most organizations this is over 100
+reports, but really the threshold is relative to the average number of
+confirmed threats per week. Example: if an org only adds 5 blocked threats per
+week, then a 7-day backlog of even 10 proposals is a really big deal.
+
+**Run via CLI:** **Implemented as \`healthchecks run reviewing.backlog\`.**
+The endpoint counts the **Needs Review** subset only (assets not
+watchlisted, or reports marked \`reportedByCustomer\`) and grades severity
+against per-org thresholds (default warn=50, fail=100; override with
+\`--warn-threshold\` / \`--fail-threshold\` via the run payload). This is
+the number the reviewing page in the app shows by default, so the
+healthcheck output matches what reviewers see.
+
+For raw counts plus SLA / age breakdowns,
+\`chainpatrol --json queues snapshot --org <slug>\` remains useful and
+exposes \`reviewQueue.totalPendingProposals\` and
+\`reviewQueue.distinctReports\` (note: \`queues snapshot\` does NOT apply
+the watchlist filter, so its number is the sum of Needs Review +
+Watchlisted). Compare against the org's typical weekly throughput
+(use \`metrics summary --this-week\` for that baseline) \u2014 a backlog that
+exceeds a week of typical confirmed-threat volume is a finding regardless
+of the absolute number.
+
+#### Really Old Needs-Review Proposals
+
+Any Needs-Review proposal waiting longer than 14 days is a sign something
+has gone wrong. Even complex investigations rarely take longer than this.
+Except for rare cases, these should be rejected or approved to prevent a
+backlog from building.
+
+**Run via CLI:** **Implemented as \`healthchecks run reviewing.old-proposals\`.**
+The endpoint counts Needs-Review proposals older than the warn / fail age
+thresholds (default 7 / 14 days) and lists the oldest offenders in
+\`findings\`. \`queues snapshot\` (\`reviewQueue.ageBuckets.gte168h\`) still
+works as a raw view, and \`reviewQueue.slaBuckets.breached\` captures the
+strictest SLA breaches separately \u2014 any non-zero value is worth raising.
+
+#### Watchlist Pile-Up / Old Watchlisted Proposals
+
+Watchlisted-pending proposals are deferred on purpose, but they shouldn't
+grow unbounded \u2014 a huge pile or very-old items signal that the watchlist
+needs a cleanup pass. These don't block on the same SLA as Needs Review.
+
+**Run via CLI:** **Implemented as \`healthchecks run reviewing.watchlist-backlog\`**
+(pile-up count, default warn=200) and
+**\`healthchecks run reviewing.watchlist-old\`** (default warn-age 30
+days). Both cap severity at warn. When reporting findings during an org
+healthcheck, group them under "watchlist cleanup" rather than mixing with
+Needs-Review findings \u2014 they're operationally different concerns.
+
+#### Spike in Auto Approved Reports
+
+If suddenly a lot of proposals in an org are being approved by automation,
+that can be a sign of a bad rule approving too much, or a break in auto
+confidences. Sometimes detection is spamming things that uniquely combine
+with a weakness of a rule \u2014 which is effectively a bad rule. In all these
+cases, notify an engineer at ChainPatrol and check any detection configs you
+adjusted recently, since those may be the cause of spam combined with a weak
+rule.
+
+**Run via CLI:** **Not yet implemented as a healthcheck endpoint.** Listed
+in \`healthchecks list\` as \`reviewing.auto-approval-spike\` with
+\`implemented: false\`. As a proxy until the endpoint lands, use
+\`chainpatrol --json metrics breakdown --org <slug> --by day --this-week\`
+and look for a sudden surge in \`newThreats\` / \`threatsWatchlisted\` that
+isn't matched by a parallel rise in reviewer activity \u2014 that gap usually
+points at automation doing the approving.
+
+### Blocklisting
+
+#### Google Safe Browsing (Coming Soon)
+
+(Needs new public API added before this works.)
+
+High error rate in Google Safe Browsing submission tracker. Each submission
+has a status. If too many are in \`CANCELLED\`, that means Google's engine
+denied our submission. Contact ChainPatrol's eng team to investigate why, and
+also take a look at the org's custom detection sources \u2014 it's possible there
+are too many false positives landing on the blocklist, indicating issues with
+detection and reviewing rules.
+
+**Run via CLI:** **Not yet implemented as a healthcheck endpoint.** Listed
+in \`healthchecks list\` as \`blocklisting.gsb-cancelled-rate\` with
+\`implemented: false\`. Until Google Safe Browsing submission state is
+exposed in the public API, this remains a manual / engineering-team check.
+
+### Takedowns
+
+The takedown pipeline has three stages \u2014 TODO (queued, not yet filed),
+IN_PROGRESS (filed, waiting on vendor / customer / refile), and a terminal
+state (COMPLETED or CANCELLED). Healthchecks cover pile-ups at each stage,
+plus quality/configuration issues.
+
+#### Too Many Takedowns in ToDo
+
+Can mean a gap in automated takedowns not being implemented for some new area
+of threats. It can also mean the areas that require manual takedowns are
+being missed by the takedown team.
+
+**Run via CLI:** **Implemented as \`healthchecks run takedowns.todo-volume\`.**
+Counts takedowns sitting in TODO (default warn=50, fail=100). For raw
+breakdowns by type, cross-reference with
+\`chainpatrol --json metrics breakdown --org <slug> --by assetType\` \u2014
+items piled up on a specific platform usually point at an automation
+gap there.
+
+#### Too Many Takedowns In Progress
+
+Typically means something is wrong with the submission itself. The takedown
+may need to be resubmitted, the vendor asked for more evidence, or we may
+have submitted it in the wrong place.
+
+**Run via CLI:** Two checks, complementary:
+
+- **\`healthchecks run takedowns.in-progress-volume\`** \u2014 counts all
+  IN_PROGRESS takedowns regardless of age (default warn=30, fail=75).
+  Catches a vendor-side or submission-format problem before items go
+  stale.
+- **\`healthchecks run takedowns.stale-in-progress\`** \u2014 counts IN_PROGRESS
+  takedowns past a staleness threshold (default 7 days), lists the oldest
+  offenders. Any non-zero value is worth investigating; a growing count
+  across snapshots strongly suggests vendor-side or format issues.
+
+#### Too Many Cancelled Takedowns
+
+Takedowns should rarely be cancelled. A cancelled takedown means "we will not
+do this takedown" for some reason. Cases like adding an item to the blocklist
+when it's already taken down are treated as completed, not cancelled. So even
+3 cancelled takedowns in a 7-day period is too many.
+
+**Run via CLI:** **Implemented as \`healthchecks run takedowns.cancelled-count\`.**
+Counts transitions into the CANCELLED status from the TakedownEvent log
+within the lookback window (default 7 days, warn=3, fail=10). The check
+uses the event log rather than \`Takedown.updatedAt\` so it correctly
+attributes the cancellation date even if the takedown has since been
+edited. A spike usually means a quality problem in the proposal funnel
+or the CANCELLED status being used as a catch-all.
+
+#### Automated Takedowns Turned Off for Over 30 Days
+
+Automated takedowns should be on by default for nearly every organization.
+Any issue that would make you want to turn off automated takedowns should be
+resolved within 30 days.
+
+**Run via CLI:** **Implemented as \`healthchecks run takedowns.automation-off\`.**
+Checks \`Organization.isAutomatedTakedownsActive\` and derives the
+off-duration from the most recent \`SERVICES_AUTOMATED_TAKEDOWNS_UPDATED\`
+entry in \`OrganizationEvent\` (default warn 30 days, fail 60 days). Orgs
+with takedown service entirely disabled (\`isTakedownsActive=0\`) are
+skipped \u2014 automation being off is implied in that case.
+
+### Assets
+
+Healthchecks on the asset model \u2014 specifically asset liveness state, which
+the takedown team depends on for follow-up.
+
+#### Spike in Recently Dead Assets
+
+A sudden spike in DEAD detections can be a good signal (takedowns or platform
+moderation working) but it can also mean the liveness checker is
+misclassifying assets after a platform change, captcha rollout, or anti-bot
+update. If many assets become dead at once, sample a few manually.
+
+**Run via CLI:** **Implemented as \`healthchecks run assets.dead-asset-spike\`.**
+Compares \`DETECTED_AS_DEAD\` events in the current window (default 24h)
+against the baseline rate from the prior \`baselineDays\` (default 7d).
+Severity fires only when the current count clears \`minSpikeCount\` (default
+10) AND exceeds the multiplier (default warn \xD72, fail \xD74). The
+\`minSpikeCount\` floor suppresses noise on orgs with near-zero baseline
+activity. When this fires, pull a sample of recent DEAD assets, verify a
+few in a browser, and notify ChainPatrol engineering if the sample is
+clearly still live.
+
+#### Assets Marked Dead but Still Online / Assets Not Marked Dead Even Though They Are Down
+
+These two opposite failure modes are **not implemented as healthchecks**
+(listed as \`assets.dead-but-alive\` and \`assets.alive-but-marked-dead\` with
+\`implemented: false\`). Both require live HTTP probes against asset URLs,
+which is not a synchronous-healthcheck shape.
+
+Until a dedicated probe command exists:
+
+- For "marked dead but still alive": sample a handful of recently-DEAD
+  assets, open them in a browser, and watch for any that load. Common
+  causes: bot protection, geo-blocking, rate limits, or liveness logic
+  that does not handle the asset type correctly.
+- For "alive but marked dead": after a known takedown event, sample
+  assets that *should* be dead but are still marked alive. Common causes:
+  cached responses, soft-404 pages, parked-domain redirects, platform
+  suspension pages still returning 200.
+
+In both cases, if liveness looks miscalibrated for a class of assets,
+notify ChainPatrol engineering \u2014 the checker likely needs a tuning pass for
+that platform.
+
+## Organization Trend Search Guide
+
+Trend search asks "what's changed recently for this org?" \u2014 the answer can
+surface coordinated attacks, new attack channels, or campaigns targeting
+specific people, **before** they show up as a healthcheck failure. Unlike
+the HealthCheck Guide above (which grades single signals against
+thresholds), trend search compares a recent window to a baseline window
+and flags ratios, not absolute counts. A trend is interesting even when
+the pipeline is keeping up with it \u2014 the user usually wants to know.
+
+When the user asks something like:
+
+- "are there any trends in org X?"
+- "search for trends in <org>"
+- "anything unusual happening with <org> lately?"
+- "any spikes for <org>?"
+- "what's new for <org> this week?"
+- "is anyone targeting <org>'s employees more than usual?"
+- "are we seeing more YouTube/Telegram/etc. threats for <org>?"
+
+\u2026run the three trend checks below in parallel (single message, multiple
+Bash calls) and surface anything where the current rate is \u2265 2\xD7 the
+baseline AND clears a small absolute floor.
+
+### How to compute "current vs. baseline" rates
+
+Pick two non-overlapping windows: a **current** window the user cares about
+(default last 7 days) and a **baseline** window ending where the current
+one starts (default the prior ~90 days, i.e. \`current_start - 90d\` \u2192
+\`current_start - 1d\`). For any breakdown bucket, compute:
+
+\`\`\`
+current_per_day  = current_count  / current_window_days
+baseline_per_day = baseline_count / baseline_window_days
+ratio            = current_per_day / max(baseline_per_day, epsilon)
+\`\`\`
+
+Flag a bucket if \`ratio >= 2\` AND \`current_count >= 5\`. The floor
+suppresses noise on orgs with near-zero baseline activity (a single new
+YouTube report jumping the rate from 0 to 1/day shouldn't trigger). If
+the user gives a different window ("last 3 days", "this month"), adjust
+both windows proportionally and keep the same ratio threshold.
+
+### Trend 1 \u2014 Spike in a specific asset type
+
+A sudden jump in threats on a platform the org doesn't usually see
+traffic on ("normally you don't get targeted on YouTube much, but now
+there's a spike there") is worth flagging \u2014 it usually means an attacker
+has discovered a new channel that works for them. Even when the absolute
+number is small, the *ratio* against the org's normal mix is what
+matters.
+
+Use \`metrics breakdown --by type\` over both windows:
+
+\`\`\`bash
+# Current window \u2014 last 7 days, broken out by asset type
+chainpatrol --json metrics breakdown --org <slug> --by type \\
+  --from <YYYY-MM-DD 7d ago> --to <YYYY-MM-DD today>
+
+# Baseline window \u2014 prior ~90 days ending where the current window starts
+chainpatrol --json metrics breakdown --org <slug> --by type \\
+  --from <YYYY-MM-DD 97d ago> --to <YYYY-MM-DD 8d ago>
+\`\`\`
+
+Each entry in \`.points\` has \`{ type, count }\`. Join the two windows on
+\`type\`, apply the ratio rule above, and report each flagged type.
+
+Cross-reference any flagged type with \`configs list --org <slug>\` \u2014 if
+the spike is on Twitter / X but \`twitter_post_search\` is disabled, the
+detection source for that channel isn't even running for this org and
+the spike is being caught by something else (likely customer reports);
+suggest turning it on.
+
+### Trend 2 \u2014 Spike in overall threat volume
+
+A sharp rise in total threats across the org \u2014 regardless of type or
+brand \u2014 usually means a coordinated attack or campaign is underway. This
+isn't a healthcheck (reviewing and takedowns may be keeping up just
+fine), but the security team still wants to know so they can warn
+customers / employees / partners.
+
+\`\`\`bash
+# Daily volume for the last ~6 weeks \u2014 enough to eyeball a baseline AND
+# see the spike on the right edge of the series.
+chainpatrol --json metrics breakdown --org <slug> --by day \\
+  --from <YYYY-MM-DD 42d ago> --to <YYYY-MM-DD today>
+\`\`\`
+
+Read \`.points\` (one entry per day). Take the trailing 7-day average and
+compare against the prior ~5 weeks (the same 2\xD7 / floor rule). For round
+totals to quote to the user, also pull:
+
+\`\`\`bash
+# Two calls \u2014 current and baseline windows \u2014 using --include to skip
+# the per-type / per-day series and keep the call cheap.
+chainpatrol --json metrics organization --org <slug> \\
+  --include reports,newThreats,threatsWatchlisted \\
+  --from <current_from> --to <current_to>
+
+chainpatrol --json metrics organization --org <slug> \\
+  --include reports,newThreats,threatsWatchlisted \\
+  --from <baseline_from> --to <baseline_to>
+\`\`\`
+
+When volume spikes broadly, also skim \`reports list --reported-by-customer\`
+for the same window \u2014 a wave of customer reports often arrives a few hours
+ahead of automated detection on a real coordinated push.
+
+### Trend 3 \u2014 Spike on a specific sub-brand (especially employee brands)
+
+Sub-brands the org has set up for individual people \u2014 employees,
+executives, public figures \u2014 are high-signal targets. A sudden spike on
+one usually means an attacker is impersonating that person specifically,
+which is materially different from a generic phishing wave and usually
+warrants a direct heads-up to the person involved. In the database these
+are \`Brand\` rows with \`type: INDIVIDUAL\` (vs. \`ORGANIZATION\` for
+product / parent brands).
+
+**Step 1: Pull the brand roster** so you can label each spike as
+"employee" or "product" without asking the user.
+
+\`\`\`bash
+chainpatrol --json brands list
+\`\`\`
+
+Build a map of \`slug \u2192 type\` from the response so the next step's
+findings can be tagged \`(employee)\` or \`(product)\` automatically.
+
+**Step 2: Run the breakdown over both windows.**
+
+\`\`\`bash
+# Current window \u2014 last 7 days, broken out by sub-brand
+chainpatrol --json metrics breakdown --org <slug> --by brand \\
+  --from <YYYY-MM-DD 7d ago> --to <YYYY-MM-DD today>
+
+# Baseline window \u2014 prior ~90 days
+chainpatrol --json metrics breakdown --org <slug> --by brand \\
+  --from <YYYY-MM-DD 97d ago> --to <YYYY-MM-DD 8d ago>
+\`\`\`
+
+Each entry in \`.points\` has \`{ brandId, brandSlug, brandName, count }\`.
+Apply the ratio rule, join against the \`slug \u2192 type\` map from Step 1,
+and report each spiking sub-brand by name plus its type.
+
+**Step 3: Drill into the flagged brand** with \`metrics organization
+--brand-slug <slug>\` for a per-day / per-type breakdown scoped to that
+brand only. The server applies the brand filter to the scalar metrics
+(\`newThreats\`, \`takedownsFiled\`, etc.) AND to \`blockedByType\` /
+\`blockedByDay\`, so the time series and per-asset-type counts are real
+brand-only data:
+
+\`\`\`bash
+chainpatrol --json metrics organization --org <slug> \\
+  --brand-slug <brand-slug> \\
+  --include newThreats,blockedByType,blockedByDay \\
+  --from <YYYY-MM-DD 7d ago> --to <YYYY-MM-DD today>
+\`\`\`
+
+If multiple \`INDIVIDUAL\` brands are spiking at the same time, treat that
+as a stronger signal than a single one \u2014 likely a campaign targeting the
+company's people rather than a single impersonation. Prioritize those
+findings over single-brand spikes when summarizing.
+
+### Reporting trend findings
+
+Report each spiking bucket as its own finding with: the trend it falls
+under (asset type / overall volume / sub-brand), the current vs. baseline
+rate (e.g. "youtube: 12/day last 7d vs. 1.2/day prior 90d, \xD710
+baseline"), and a one-line follow-up:
+
+- Asset-type spike \u2192 check \`configs list\` for the matching detection
+  source and turn it on if it's off.
+- Overall-volume spike \u2192 flag a possible coordinated campaign; suggest
+  the security team look at the recent \`reports list\` for shared
+  infrastructure (sender, registrar, hosting).
+- Sub-brand spike \u2192 look up \`type\` via \`brands list\`; if
+  \`INDIVIDUAL\`, suggest a direct heads-up to that person; if
+  \`ORGANIZATION\`, suggest a product-team alert.
+
+If none of the three trends fire above the 2\xD7 / floor thresholds, say so
+explicitly ("no significant trends in the last 7 days vs. the prior 90")
+rather than dumping every breakdown number \u2014 the absence is the
+finding.
+`;
+}
+
+// src/skill/cli.ts
+var import_meta = {};
+var SKILL_DIR = path.join(os.homedir(), ".claude", "skills", "chainpatrol");
+var SKILL_FILE = path.join(SKILL_DIR, "SKILL.md");
+function getVersion() {
+  const thisDir = path.dirname(url.fileURLToPath(import_meta.url));
+  let dir = thisDir;
+  for (let i = 0; i < 5; i++) {
+    const candidate = path.join(dir, "package.json");
+    if (fs.existsSync(candidate)) {
+      const pkg = JSON.parse(fs.readFileSync(candidate, "utf-8"));
+      if (pkg.name === "@chainpatrol/sdk" && pkg.version) {
+        return pkg.version;
+      }
+    }
+    dir = path.dirname(dir);
+  }
+  return "0.0.0";
+}
+function main() {
+  const version = getVersion();
+  const content = buildSkillContent(version);
+  const alreadyExists = fs.existsSync(SKILL_FILE);
+  const upToDate = alreadyExists && fs.readFileSync(SKILL_FILE, "utf-8") === content;
+  if (upToDate) {
+    console.log(JSON.stringify({ status: "up-to-date", path: SKILL_FILE, version }));
+    return;
+  }
+  fs.mkdirSync(SKILL_DIR, { recursive: true });
+  fs.writeFileSync(SKILL_FILE, content, { mode: 420 });
+  const status = alreadyExists ? "updated" : "installed";
+  console.log(JSON.stringify({ status, path: SKILL_FILE, version }));
+}
+main();
+//# sourceMappingURL=cli.js.map
+//# sourceMappingURL=cli.js.map