crawlforge-mcp-server 6.0.0 → 6.2.0

package/src/core/ElicitationHelper.js

@@ -1,36 +1,56 @@
 /**
  * ElicitationHelper — MCP Elicitation for CrawlForge
  *
- * Allows tools to request user confirmation or input mid-execution for
- * expensive or ambiguous operations. Falls back gracefully when the
- * MCP client does not support elicitation.
+ * Allows tools to request user confirmation before an expensive or ambiguous
+ * operation. Falls back gracefully when the MCP client cannot be asked.
  *
- * The request goes out as a 2025-era server→client `elicitation/create`,
- * awaited inline in the middle of a tool's work. Two things the SDK does NOT
- * do for us, and which `supported` therefore decides before we send:
+ * Phase 4.4 moved confirmations from an inline server→client request to the
+ * 2026-07-28 MULTI-ROUND-TRIP form: `confirm()` no longer sends anything and no
+ * longer awaits. It returns a verdict, and when the user must be asked the
+ * verdict carries an `input_required` result for the tool to RETURN. The SDK
+ * then either hands it to a 2026-era client or, on a 2025-era connection, runs
+ * its own legacy shim (real `elicitation/create` + handler re-entry). One shape
+ * serves both eras, which is why nothing here branches on the protocol version
+ * any more — the previous era guard reported "unsupported" on 2026-07-28 and
+ * every prompt there was silently skipped.
  *
- *   - `Server.elicitInput()` refuses a client that declared a bare
- *     `elicitation: {}` (it demands `elicitation.form`), even though the SDK's
- *     own capability rule counts a bare declaration as form-capable — that is
- *     the pre-mode 2025 meaning, and it is what the SDK's legacy shim and its
- *     2026 seam both apply. We send through `Server.request()`, which applies
- *     that same lenient rule, so those clients get their prompt.
+ * THE HANDLER IS RE-ENTERED. Everything a tool does above its gate runs a
+ * second time when the answer arrives, so a gate belongs above every fetch and
+ * every side effect. Billing is not a caller's problem: `withAuth` charges an
+ * `input_required` return zero and reports no usage, so a round trip and a
+ * declined confirmation are both free (G4).
  *
- *   - Both `elicitInput()` and `request()` throw on a 2026-07-28-era
- *     connection: that revision has no server→client request channel at all.
- *     There is no inline substitute — the replacement is an `input_required`
- *     result RETURNED by a tools/call handler, which this helper cannot do
- *     from the middle of a tool's execution. So `supported` reports false and
- *     the operation proceeds unasked, exactly as it does for a client with no
- *     elicitation capability. A confirmation prompt is a nicety; failing the
- *     call is not an acceptable substitute. See docs/mcp-spec-adoption.md.
+ * Two properties of the old helper are deliberately preserved:
+ *
+ *   - **Fail-open.** A client that never declared elicitation is not asked, and
+ *     the operation proceeds. This is not politeness — the SDK answers an
+ *     `input_required` return on such a connection with `isError: true`
+ *     ("did not declare the required capability"), so dropping the capability
+ *     gate would turn a nicety into a failed call. Verified against the SDK.
+ *   - **We ask at most once.** `inputResponses` is absent on a first entry and
+ *     present on a retry, so a retry whose answer did not survive the trip
+ *     (a dropped key, an answer of another kind) proceeds rather than asking
+ *     again until the shim's round limit fails the call.
+ *
+ * The one case that cannot be preserved: a client that DECLARES elicitation and
+ * then throws answering it now yields an `isError` result from the SDK where the
+ * old inline path proceeded. The failure happens inside the SDK after the
+ * handler has returned, so nothing here can intercept it. It costs nothing — the
+ * handler did no work, so `withAuth` bills zero.
+ *
+ * Which server instance we ask matters as much as what we ask. server.js
+ * constructs this against the top-level template McpServer, but neither HTTP
+ * leg serves from it — the 2025-era path connects a clone per session and the
+ * modern leg builds one per request, so the template is never `.connect()`ed
+ * and reports no client capabilities. The transport stamps the serving clone on
+ * the request context; this resolves it from there and falls back to the
+ * injected instance, which on stdio IS the connected one. On a 2026-era request
+ * there is no connected instance to read at all — capabilities arrive per
+ * request in the `_meta` envelope, which is why `ctx` is consulted first.
  */
 
-/**
- * First revision of the modern protocol era. Revisions are ISO dates, so
- * lexicographic comparison orders them chronologically (the SDK's own rule).
- */
-const FIRST_MODERN_PROTOCOL_VERSION = '2026-07-28';
+import { inputRequired, inputResponse, CLIENT_CAPABILITIES_META_KEY } from '@modelcontextprotocol/server';
+import { servingRequestId, servingServer } from '../server/requestContext.js';
 
 /** The one-boolean schema a confirmation asks with. */
 const CONFIRM_SCHEMA = {
@@ -70,69 +90,101 @@ export class ElicitationHelper {
   }
 
   /**
-   * Whether an inline elicitation round trip will actually reach the user.
-   * @returns {boolean}
+   * The McpServer this request is served from: the clone the transport stamped
+   * on the request context, else the constructor-injected instance (stdio, and
+   * any caller outside a request context).
+   * @private
+   */
+  get _server() {
+    return servingServer() ?? this._mcpServer;
+  }
+
+  /**
+   * The client's declared capabilities for the request in flight. A 2026-era
+   * request carries them per-request in the `_meta` envelope and has no
+   * connected server instance to read; a 2025-era one has them on the serving
+   * instance and no envelope.
+   * @private
    */
-  get supported() {
-    const server = this._mcpServer?.server;
-    if (typeof server?.request !== 'function') return false;
+  _clientCapabilities(ctx) {
+    const fromEnvelope = ctx?.mcpReq?.envelope?.[CLIENT_CAPABILITIES_META_KEY];
+    if (fromEnvelope) return fromEnvelope;
     try {
-      // No server→client request channel exists on the 2026-07-28 era.
-      const negotiated = server.getNegotiatedProtocolVersion?.();
-      if (typeof negotiated === 'string' && negotiated >= FIRST_MODERN_PROTOCOL_VERSION) return false;
-      return formElicitationDeclared(server.getClientCapabilities?.());
+      return this._server?.server?.getClientCapabilities?.();
     } catch {
-      return false;
+      return undefined;
     }
   }
 
   /**
-   * Send one form-mode `elicitation/create` and return the ElicitResult.
-   * This is byte-for-byte the message `Server.elicitInput()` sends; it just
-   * does not impose that method's stricter `elicitation.form` gate.
-   * @private
+   * Whether asking will actually reach the user rather than fail the call.
+   * @param {object} [ctx] the SDK per-request context the handler received
+   * @returns {boolean}
    */
-  async _elicit(message, requestedSchema) {
-    return this._mcpServer.server.request({
-      method: 'elicitation/create',
-      params: { message, requestedSchema, mode: 'form' },
-    });
+  supported(ctx) {
+    return formElicitationDeclared(this._clientCapabilities(ctx));
   }
 
   /**
    * Ask for user confirmation before proceeding with an expensive operation.
-   * Returns true if confirmed (or if elicitation is unsupported — fail-open
-   * so tools continue working in non-elicitation clients).
+   * SYNCHRONOUS — it performs no I/O. Do not `await` it.
    *
-   * @param {string} message - Human-readable explanation of what requires confirmation
-   * @param {object} [details] - Additional context (projected cost, URL count, etc.)
-   * @returns {Promise<boolean>} - true = proceed, false = cancel
+   * @param {object|undefined} ctx - the SDK per-request context the handler received
+   * @param {string} key - stable identifier for this question, unique across tools
+   * @param {string} message - human-readable explanation of what requires confirmation
+   * @param {object} [details] - additional context (projected cost, URL count, etc.)
+   * @returns {{status:'proceed'}|{status:'cancelled'}|{status:'ask', result: object}}
+   *   `ask` carries an `input_required` result the caller must RETURN verbatim.
    */
-  async confirm(message, details = {}) {
-    if (!this.supported) {
-      this._logger.warn('Elicitation not supported by client — proceeding without confirmation', { message });
-      return true;
-    }
+  confirm(ctx, key, message, details = {}) {
+    const responses = ctx?.mcpReq?.inputResponses;
+    const answered = inputResponse(responses, key);
 
-    try {
-      const detailLines = Object.entries(details)
-        .map(([k, v]) => `  ${k}: ${v}`)
-        .join('\n');
-      const fullMessage = detailLines ? `${message}\n\n${detailLines}` : message;
+    if (answered.kind === 'elicit') {
+      // Only an explicit accept + confirmed=true proceeds; decline/cancel = stop.
+      return answered.action === 'accept' && answered.content?.confirmed === true
+        ? { status: 'proceed' }
+        : { status: 'cancelled' };
+    }
 
-      const result = await this._elicit(fullMessage, CONFIRM_SCHEMA);
+    // A retry carries an `inputResponses` object even when this key's answer
+    // did not survive it. Asking again would burn the shim's rounds and end in
+    // a failed call, so one unanswered round trip proceeds instead.
+    if (responses !== undefined) {
+      this._logger.warn('Elicitation answer did not come back — proceeding without confirmation', { key });
+      return { status: 'proceed' };
+    }
 
-      // Only an explicit accept + confirmed=true proceeds; decline/cancel = stop.
-      return result?.action === 'accept' && result?.content?.confirmed === true;
-    } catch (err) {
-      this._logger.warn('Elicitation request failed — proceeding without confirmation', { error: err.message });
-      return true; // fail-open
+    if (!this.supported(ctx)) {
+      this._logger.warn('Elicitation not supported by client — proceeding without confirmation', { message });
+      return { status: 'proceed' };
     }
+
+    const detailLines = Object.entries(details)
+      .map(([k, v]) => `  ${k}: ${v}`)
+      .join('\n');
+    const fullMessage = detailLines ? `${message}\n\n${detailLines}` : message;
+
+    return {
+      status: 'ask',
+      result: inputRequired({
+        inputRequests: {
+          [key]: inputRequired.elicit({ message: fullMessage, requestedSchema: CONFIRM_SCHEMA }),
+        },
+      }),
+    };
   }
 
   /**
    * Ask the user to provide a string value (e.g. missing schema field).
    *
+   * Still the 2025-era inline form, and still reached by no tool — this is the
+   * repo's one caller-less elicitation path, left as-is under G6 (dead code is
+   * reported, not deleted). It therefore keeps the era guard that `confirm()`
+   * shed: an inline request throws on a 2026-era connection, so the default is
+   * returned there rather than the call being failed. Converting it to a round
+   * trip is speculative until something calls it.
+   *
    * @param {string} message
    * @param {object} [options]
    * @param {string} [options.fieldName]
@@ -141,24 +193,43 @@ export class ElicitationHelper {
    * @returns {Promise<string|null>} - The user-provided value or null if cancelled/unsupported
    */
   async requestString(message, { fieldName = 'value', fieldDescription = '', defaultValue } = {}) {
-    if (!this.supported) {
+    const server = this._server?.server;
+    const inlineUsable = typeof server?.request === 'function'
+      && !this._modernEra(server)
+      && formElicitationDeclared(this._clientCapabilities());
+
+    if (!inlineUsable) {
       this._logger.warn('Elicitation not supported — using default value', { fieldName, defaultValue });
       return defaultValue || null;
     }
 
     try {
-      const result = await this._elicit(message, {
-        type: 'object',
-        properties: {
-          [fieldName]: {
-            type: 'string',
-            title: fieldName,
-            description: fieldDescription,
-            ...(defaultValue ? { default: defaultValue } : {}),
+      // relatedRequestId ties the prompt to the tools/call in flight. Without it
+      // the 2025-era HTTP transport puts the request on the standalone GET SSE
+      // stream and drops it outright when the client never opened one.
+      const relatedRequestId = servingRequestId();
+      const result = await server.request(
+        {
+          method: 'elicitation/create',
+          params: {
+            message,
+            requestedSchema: {
+              type: 'object',
+              properties: {
+                [fieldName]: {
+                  type: 'string',
+                  title: fieldName,
+                  description: fieldDescription,
+                  ...(defaultValue ? { default: defaultValue } : {}),
+                },
+              },
+              required: [fieldName],
+            },
+            mode: 'form',
           },
         },
-        required: [fieldName],
-      });
+        relatedRequestId === null ? undefined : { relatedRequestId }
+      );
 
       // The answer is client-supplied and no longer schema-checked by the SDK
       // on this path, so hold it to the type we asked for.
@@ -171,4 +242,14 @@ export class ElicitationHelper {
       return defaultValue || null;
     }
   }
+
+  /** @private The 2026-07-28 era has no server→client request channel. */
+  _modernEra(server) {
+    try {
+      const negotiated = server?.getNegotiatedProtocolVersion?.();
+      return typeof negotiated === 'string' && negotiated >= '2026-07-28';
+    } catch {
+      return false;
+    }
+  }
 }

package/src/server/requestContext.js

@@ -69,3 +69,53 @@ export function setActualCost(n) {
 export function reportedActualCost() {
   return requestContext.getStore()?.actualCost ?? null;
 }
+
+/**
+ * Record the McpServer instance that is actually serving this request, and the
+ * wire era it speaks.
+ *
+ * Neither HTTP leg serves from the top-level McpServer that server.js
+ * registers everything on: the 2025-era path connects one clone per session,
+ * and the modern leg builds a fresh clone per request (see
+ * transports/streamableHttp.js). Only a clone is ever `.connect()`ed, so only a
+ * clone has a negotiated protocol version, the client's declared capabilities,
+ * and a channel to send a server-to-client request on. The template has none of
+ * those, which is why anything reading them off it (ElicitationHelper) got
+ * `undefined` on every HTTP request.
+ *
+ * Stdio stamps nothing: there the top-level instance IS the connected one, and
+ * the accessors below return null so callers fall back to it.
+ *
+ * @param {object|null} server the serving McpServer
+ * @param {'legacy'|'modern'|null} [era] the wire era it serves
+ */
+export function setServingServer(server, era = null) {
+  const store = requestContext.getStore();
+  if (!store) return;
+  store.servingServer = server ?? null;
+  store.servingEra = era;
+}
+
+/** The McpServer serving this request, or null on stdio / outside a context. */
+export function servingServer() {
+  return requestContext.getStore()?.servingServer ?? null;
+}
+
+/** The wire era serving this request: 'legacy' | 'modern' | null (stdio). */
+export function servingEra() {
+  return requestContext.getStore()?.servingEra ?? null;
+}
+
+/**
+ * The JSON-RPC id of the request being served, or null when unknown.
+ *
+ * A server-to-client request sent from inside a tool has to say which inbound
+ * request it belongs to: the 2025-era streamable HTTP transport routes an
+ * unrelated request to the standalone GET SSE stream and silently DROPS it when
+ * the client never opened one, which turns an elicitation prompt into a
+ * 60-second stall before it fails open. withAuth stamps this from the SDK's
+ * per-request `ctx`; stdio has no streams to pick between and ignores it.
+ */
+export function servingRequestId() {
+  return requestContext.getStore()?.servingRequestId ?? null;
+}

package/src/server/transports/streamableHttp.js

@@ -31,7 +31,7 @@ import { NodeStreamableHTTPServerTransport, toNodeHandler, toWebRequest } from "
 import { createServer } from 'node:http';
 import { createHash, randomUUID, timingSafeEqual } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { requestContext } from '../requestContext.js';
+import { requestContext, setServingServer } from '../requestContext.js';
 import { applySpecHygiene } from '../specHygiene.js';
 
 const pkg = JSON.parse(readFileSync(new URL('../../../package.json', import.meta.url), 'utf8'));
@@ -214,7 +214,14 @@ export async function connectStreamableHttp(server, authManager, logger, options
   // this handler, so the modern leg never has to serve one. The SDK owns the
   // Content-Type gate (415), the Mcp-Method/Mcp-Name cross-checks (-32020 on
   // 400) and `server/discover`; nothing here re-implements them.
-  const modernHandler = createMcpHandler(() => cloneServerForSession(server), {
+  // The factory runs once per request, inside the requestContext.run() below,
+  // so the clone it builds can be stamped on the store: that clone — never the
+  // template — is the instance this request is actually served from.
+  const modernHandler = createMcpHandler((ctx) => {
+    const requestServer = cloneServerForSession(server);
+    setServingServer(requestServer, ctx?.era ?? 'modern');
+    return requestServer;
+  }, {
     legacy: 'reject',
     onerror: (err) => logger.warn('2026-era MCP request rejected', { error: err?.message })
   });
@@ -362,7 +369,10 @@ export async function connectStreamableHttp(server, authManager, logger, options
       const existing = sessionIdHeader ? sessions.get(String(sessionIdHeader)) : undefined;
 
       if (existing) {
-        await requestContext.run({ internal }, () => existing.transport.handleRequest(req, res, parsedBody));
+        await requestContext.run(
+          { internal, servingServer: existing.server, servingEra: 'legacy' },
+          () => existing.transport.handleRequest(req, res, parsedBody)
+        );
         return;
       }
 
@@ -395,7 +405,10 @@ export async function connectStreamableHttp(server, authManager, logger, options
 
       try {
         await sessionServer.connect(transport);
-        await requestContext.run({ internal }, () => transport.handleRequest(req, res, parsedBody));
+        await requestContext.run(
+          { internal, servingServer: sessionServer, servingEra: 'legacy' },
+          () => transport.handleRequest(req, res, parsedBody)
+        );
       } catch (err) {
         logger.error('Streamable HTTP session initialization failed', { error: err?.message });
         safeClose(transport);

package/src/server/withAuth.js

@@ -8,7 +8,11 @@
  *     so a valid API key is required for every invocation
  *   - try/finally guarantees a single `tool invocation` log line per call
  *   - log payload: { toolName, paramHash, durationMs, outcome, creditCost, creatorMode }
- *   - outcome ∈ { 'success' | 'error' | 'insufficient_credits' }
+ *   - outcome ∈ { 'success' | 'error' | 'insufficient_credits' | 'input_required' }
+ *   - an `input_required` return (Phase 4.4) is a round trip, not an answer: the
+ *     handler did no work, so it is billed NOTHING and reports no usage. The
+ *     SDK re-enters the handler with the reply and the terminal entry bills
+ *     once, so a confirmation costs exactly what the call always cost (G4).
  *   - error results get a "Next step:" hint naming the tool to try next
  *     (src/server/fallbackHints.js) so a failure is not followed by a blind retry
  *   - emits an OTel span via src/observability/tracing.js (no-op if disabled)
@@ -16,6 +20,7 @@
  */
 
 import { createHash } from 'node:crypto';
+import { isInputRequiredResult } from '@modelcontextprotocol/server';
 import { recordToolInvocation } from '../observability/tracing.js';
 import { isInternalRequest, preflightRefusal, reportedActualCost, requestContext } from './requestContext.js';
 import { appendFallbackHint } from './fallbackHints.js';
@@ -71,7 +76,7 @@ export function hashParams(params) {
  */
 export function makeWithAuth({ authManager, logger, metrics = null, mcpServer = null }) {
   return function withAuth(toolName, handler) {
-    const invoke = async (params) => {
+    const invoke = async (params, ctx) => {
       const startTime = Date.now();
       const paramHash = hashParams(params);
       const creatorMode = authManager.isCreatorMode();
@@ -109,7 +114,14 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
         // end user's credits before forwarding — checking the static key's
         // balance here would gate users on an unrelated account).
         if (!billingExempt) {
-          const hasCredits = await authManager.checkCredits(creditCost);
+          const hasCredits = await authManager.checkCredits(creditCost, ctx);
+          // The low-credit warning asks as a round trip (Phase 4.4). Nothing has
+          // run, so this costs nothing and reports no usage; the SDK re-enters
+          // with the answer.
+          if (isInputRequiredResult(hasCredits)) {
+            outcome = 'input_required';
+            return hasCredits;
+          }
           if (!hasCredits) {
             outcome = 'insufficient_credits';
             return {
@@ -127,7 +139,21 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
         }
 
         handlerStarted = true;
-        const result = await handler(params);
+        const result = await handler(params, ctx);
+
+        // Phase 4.4: a multi-round-trip handler answers `input_required` when it
+        // needs the user before it can start. Nothing was fetched, so nothing is
+        // owed: no charge, no usage report, and none of the result stages below
+        // (there is no result yet to redact, shape or price). The SDK gathers the
+        // answer and re-enters this same wrapper; whichever entry finally returns
+        // a real result is the one that bills, exactly once. Without this branch
+        // an `input_required` is not `isError`, so it books as a success and
+        // bills in full on every round — up to eight — for a call that did no
+        // work, and a declined confirmation bills too (G4).
+        if (isInputRequiredResult(result)) {
+          outcome = 'input_required';
+          return result;
+        }
 
         // Tools catch their own failures and return { isError:true } rather than
         // throwing (the shared pattern in server.js). That is still an ERROR
@@ -275,11 +301,23 @@ export function makeWithAuth({ authManager, logger, metrics = null, mcpServer =
 
     // Every invocation runs in its own context so the compliance gate can stamp
     // a refusal where the billing decision can see it. Any outer store (the
-    // HTTP transport's `internal` flag) is spread in, not replaced — and stdio
-    // callers, who have no transport-provided store, get one here.
-    return async (params) => requestContext.run(
-      { ...(requestContext.getStore() ?? {}), preflightRefusal: null, actualCost: null },
-      () => invoke(params)
+    // HTTP transport's `internal` flag, the serving McpServer) is spread in,
+    // not replaced — and stdio callers, who have no transport-provided store,
+    // get one here.
+    //
+    // `ctx` is the SDK's per-request context (v2 calls a tool callback with
+    // `(args, ctx)`). It is passed straight through to the handler; existing
+    // 1-arity handlers ignore it. Its request id is stamped on the context so a
+    // server-to-client request sent from inside the tool can ride the same
+    // stream as this call — see servingRequestId() in requestContext.js.
+    return async (params, ctx) => requestContext.run(
+      {
+        ...(requestContext.getStore() ?? {}),
+        preflightRefusal: null,
+        actualCost: null,
+        servingRequestId: ctx?.mcpReq?.id
+      },
+      () => invoke(params, ctx)
     );
   };
 }

package/src/skills/agent-skills/crawlforge-change-tracking/SKILL.md

@@ -68,7 +68,14 @@ CLI: `crawlforge track https://example.com --selector ".price" --threshold 1`.
 
 ## Scheduled monitoring & notifications
 
-Run continuous monitoring with webhooks instead of polling manually:
+`create_scheduled_monitor` repeats `compare` on a schedule and notifies on
+change. It comes in two kinds.
+
+**Local** (default): persisted in `~/.crawlforge/monitors/`; fires in-process
+only while this MCP server runs (missed runs catch up on restart; `crawlforge
+monitor:run-due` from system cron guarantees firing). Notifies by webhook or
+Slack — never email. `goal` (plain-English LLM judge) and
+`notificationThreshold` apply to local monitors only.
 
 ```json
 {
@@ -76,19 +83,47 @@ Run continuous monitoring with webhooks instead of polling manually:
   "params": {
     "url": "https://example.com/pricing",
     "operation": "create_scheduled_monitor",
-    "monitoringOptions": {
-      "enabled": true,
-      "interval": 300000,
-      "notificationThreshold": "moderate",
-      "enableWebhook": true,
-      "webhookUrl": "https://my-site.com/notify"
+    "scheduledMonitorOptions": { "interval": 1800000, "notificationThreshold": "moderate" },
+    "notificationOptions": { "webhook": { "enabled": true, "url": "https://my-site.com/notify" } }
+  }
+}
+```
+
+**Hosted** (`scheduledMonitorOptions.hosted: true`): registered with
+CrawlForge's hosted monitors API under your API key; nothing is created locally
+and this process never fetches the page. CrawlForge's own scheduler runs every
+check whether or not this process is alive, records it, and notifies by email
+and signed webhook on every changed, new, blocked or errored page. Passing
+`goal` or `notificationThreshold` adds a `warnings` entry.
+
+```json
+{
+  "tool": "track_changes",
+  "params": {
+    "url": "https://example.com/pricing",
+    "operation": "create_scheduled_monitor",
+    "trackingOptions": { "customSelectors": [".price"] },
+    "scheduledMonitorOptions": { "hosted": true, "interval": 21600000 },
+    "notificationOptions": {
+      "email": { "enabled": true, "recipients": ["you@example.com"] },
+      "webhook": { "enabled": true, "url": "https://my-site.com/notify" }
     }
   }
 }
 ```
 
-CLI (runs until Ctrl+C):
-`crawlforge monitor https://example.com --interval 60 --webhook https://my-site.com/notify`.
+Hosted mapping: each `customSelectors` entry becomes a target selector on the
+URL; `schedule` (cron) passes through, otherwise `interval` becomes a cron of
+5–60 minutes dividing 60, whole hours dividing 24, or daily — other values
+round to the nearest and `warnings` says what they became. Up to 5 email
+recipients. `webhook.signingSecret` (16–128 chars) becomes the webhook secret;
+omit it and the response returns a generated `webhookSecret`. The response's
+`monitor` carries the hosted `id`, `nextRunAt`, `estimatedCreditsPerMonth` and
+a `dashboardUrl` for managing it.
+
+CLI: `crawlforge monitor:create <url> --every 1800 --webhook <url>` (local) or
+`crawlforge monitor:create <url> --hosted --email you@example.com` (hosted);
+`monitor:list` shows both kinds and `monitor:stop <id>` removes either.
 
 ## Other operations
 
@@ -99,10 +134,12 @@ CLI (runs until Ctrl+C):
 | `monitor` | One monitoring pass. |
 | `get_history` | Retrieve past change records (`queryOptions`). |
 | `get_stats` | Summary statistics for a tracked URL. |
-| `create_scheduled_monitor` / `stop_scheduled_monitor` | Manage cron-style monitors. |
+| `create_scheduled_monitor` | Recurring `compare` + notify; local by default, `scheduledMonitorOptions.hosted: true` for a CrawlForge-run monitor (see above). |
+| `list_scheduled_monitors` | Local monitors (`hosted: false`) then hosted ones (`hosted: true`), with `localCount`/`hostedCount`; `hostedError` if the website is unreachable. |
+| `stop_scheduled_monitor` | By `scheduledMonitorOptions.monitorId`: stops a local monitor, or deletes the hosted one with that id. By `url` alone: stops every local monitor on it and deletes hosted monitors whose targets are all that exact URL. |
 | `get_dashboard` | Aggregate status, recent alerts, trends. |
 | `export_history` | Export change history as `json` or `csv`. |
-| `create_alert_rule` | Conditional alerts (webhook / email / slack). |
+| `create_alert_rule` | Conditional alerts fired from `compare` (webhook / slack; the email action is not sent by a local process — use a hosted monitor for email). |
 | `generate_trend_report` | Trend analysis over time. |
 | `get_monitoring_templates` | List built-in monitoring presets. |
 
@@ -111,6 +148,8 @@ against the baseline without re-fetching.
 
 ## Cost note
 
-`track_changes` = 3 credits per call. A typical watch is one `create_baseline`
-plus periodic `compare` calls; scheduled monitors run server-side and notify via
-webhook/Slack so you don't pay for manual polling loops.
+`track_changes` = 3 credits per call, except that creating a hosted monitor or
+stopping a hosted-only one charges 0 (3 is the projected ceiling). A typical
+watch is one `create_baseline` plus periodic `compare` calls, or one scheduled
+monitor. Each hosted check bills 3 credits per compared target to your account;
+blocked and errored targets are free.