x-developer 2.6.5 → 2.6.6

package/skills/x-twitter-scraper/references/mcp-tools.md

@@ -1,21 +1,11 @@
-# Xquik MCP Tools Reference
+# Xquik MCP tools reference
 
-The MCP server at `https://xquik.com/mcp` provides 2 structured API tools. The agent sends API requests through the server, which handles authentication and execution for `xquik.com/api/v1`.
+The MCP server at `https://xquik.com/mcp` provides 2 API tools. The client sends requests through the server, which authenticates calls to `xquik.com/api/v1`.
 
 Hosted MCP v2.6.0 supports `2026-07-28` through `server/discover`.
 Current MCP SDKs add request metadata and headers automatically.
 Modern calls need no initialization session.
 
-## Contents
-
-- [Tools](#tools)
-- [Safety Gates](#safety-gates)
-- [Tool Selection Rules](#tool-selection-rules)
-- [Workflow Patterns](#workflow-patterns)
-- [Common Mistakes](#common-mistakes)
-- [Unsupported Operations](#unsupported-operations)
-- [Usage Reference](#usage-reference)
-
 ## Tools
 
 | Tool | Description | Usage |
@@ -23,9 +13,9 @@ Modern calls need no initialization session.
 | `explore` | Search the API endpoint catalog (read-only, no network calls) | Included |
 | `xquik` | Send confirmed Xquik API requests | Varies by endpoint |
 
-### `explore` - Search the API Spec
+### Search the API spec with `explore`
 
-The tool provides an in-memory `spec.endpoints` array. Filter/search it to find endpoints before calling them.
+The tool provides an in-memory `spec.endpoints` array. Search or filter it before calling an endpoint.
 
 ```typescript
 interface EndpointInfo {
@@ -42,20 +32,20 @@ interface EndpointInfo {
 declare const spec: { endpoints: EndpointInfo[] };
 ```
 
-Examples:
+For example:
 
 ```javascript
-// Find all included-usage endpoints
+// Find all included-usage endpoints.
 async () => spec.endpoints.filter(e => e.free);
 
-// Find endpoints by category
+// Find endpoints by category.
 async () => spec.endpoints.filter(e => e.category === 'x-write');
 
-// Search by keyword
+// Search summaries by keyword.
 async () => spec.endpoints.filter(e => e.summary.toLowerCase().includes('tweet'));
 ```
 
-### `xquik` - Send API Requests
+### Send API requests with `xquik`
 
 The tool provides `xquik.request()` with authentication and required idempotency headers injected automatically. Never pass API keys or headers. The sandbox reuses each generated key for bounded transient retries. After an unresolved write failure, verify state. Start a new attempt only when `safe_to_retry` is true and the user approves.
 
@@ -63,13 +53,13 @@ For `409 coverage_cursor_unavailable`, wait the exact `Retry-After` seconds and
 retry the same cursor once. For `410 coverage_cursor_gone`, the response omits
 `Retry-After`. Restart without a cursor and deduplicate by ID.
 
-## Safety Gates
+## Require approval
 
-Apply these gates before using `xquik`:
+Apply these rules before using `xquik`:
 
 | Capability | Rule |
 |------------|------|
-| Public writes | Show the exact tweet, reply, like, retweet, follow, unfollow, profile, or community action and wait for explicit approval. |
+| Public writes | Show the exact tweet, reply, like, retweet, follow, unfollow, profile, or community action. Wait for explicit approval. |
 | Direct messages | Show sender, recipient, and message text. Never send bulk or automatic DMs. |
 | Persistent resources | Create monitors and webhooks only when the user explicitly asks for ongoing delivery. Show target, event types, URL, and ongoing usage before creation. |
 | Private reads | Confirm before fetching DMs, bookmarks, notifications, or home timeline. Forward returned private data to other tools only after explicit approval. |
@@ -87,7 +77,7 @@ declare const xquik: {
 declare const spec: { endpoints: EndpointInfo[] };
 ```
 
-## Tool Selection Rules
+## Tool selection rules
 
 Use `explore` first to find endpoints, then `xquik` to call them.
 
@@ -96,81 +86,81 @@ Use `explore` first to find endpoints, then `xquik` to call them.
 | Single tweet by ID or URL | `GET /api/v1/x/tweets/{id}` |
 | Full X Article by tweet ID | `GET /api/v1/x/articles/{tweetId}` |
 | Search tweets by keyword/hashtag | `GET /api/v1/x/tweets/search?q=...` |
-| User profile, bio, follower counts | `GET /api/v1/x/users/{id}` (`id` can be username or numeric ID) |
+| User profile, bio, and follower counts | `GET /api/v1/x/users/{id}`; `id` accepts a username or numeric ID |
 | Download media from tweets | `POST /api/v1/x/media/download` |
 | Check follow relationship | `GET /api/v1/x/followers/check?source=A&target=B` |
-| Trending topics by region (X) | `GET /api/v1/trends?woeid=1` |
-| Trending news from 7 sources | `GET /api/v1/radar` (via `xquik` tool) |
+| X trending topics by region | `GET /api/v1/trends?woeid=1` |
+| Trending news from 7 sources | `GET /api/v1/radar` through `xquik` |
 | Activity from monitored accounts | `GET /api/v1/events` |
 | Credit balance | `GET /api/v1/credits` |
-| Monitor an X account | `POST /api/v1/monitors` (persistent; confirmation required) |
-| Set up webhook notifications | `POST /api/v1/webhooks` (persistent; confirmation required) |
+| Monitor an X account | `POST /api/v1/monitors`; persistent and requires approval |
+| Set up webhook notifications | `POST /api/v1/webhooks`; persistent and requires approval |
 | Run a giveaway draw | `POST /api/v1/draws` |
-| Compose/draft a tweet | `POST /api/v1/compose` (3-step: compose, refine, score) |
+| Compose or draft a tweet | `POST /api/v1/compose`; run compose, refine, then score |
 | Link your X username | Use the Xquik dashboard account settings |
 | Analyze tweet style | `POST /api/v1/styles` |
 | Get cached style | `GET /api/v1/styles/{id}` |
 | Compare two styles | `GET /api/v1/styles/compare` |
-| Post a tweet | `POST /api/v1/x/tweets` (confirmation required) |
-| Like/unlike a tweet | `POST` or delete request to `/api/v1/x/tweets/{id}/like` (confirmation required) |
-| Retweet | `POST /api/v1/x/tweets/{id}/retweet` (confirmation required) |
-| Unretweet | delete request to `/api/v1/x/tweets/{id}/retweet` (confirmation required) |
-| Follow/unfollow | `POST` or delete request to `/api/v1/x/users/{id}/follow` (confirmation required) |
-| Send a DM | `POST /api/v1/x/dm/{userId}` (confirmation required) |
-| Upload media | `POST /api/v1/x/media` (confirmation required before use in a post or profile change) |
+| Post a tweet | `POST /api/v1/x/tweets`; requires approval |
+| Like or unlike a tweet | `POST /api/v1/x/tweets/{id}/like` likes it. A delete request to the same route unlikes it. Both require approval. |
+| Retweet | `POST /api/v1/x/tweets/{id}/retweet`; requires approval |
+| Unretweet | Send a delete request to `/api/v1/x/tweets/{id}/retweet`; requires approval |
+| Follow or unfollow | `POST /api/v1/x/users/{id}/follow` follows. A delete request to the same route unfollows. Both require approval. |
+| Send a DM | `POST /api/v1/x/dm/{userId}`; requires approval |
+| Upload media | `POST /api/v1/x/media`; approve its use in a post or profile change |
 | Open support ticket | `POST /api/v1/support/tickets` |
 | List support tickets | `GET /api/v1/support/tickets` |
 | Get user's recent tweets | `GET /api/v1/x/users/{id}/tweets` |
 | Get user's liked tweets | `GET /api/v1/x/users/{id}/likes` |
 | Get user's media tweets | `GET /api/v1/x/users/{id}/media` |
-| Get tweet favoriters (who liked) | `GET /api/v1/x/tweets/{id}/favoriters` |
+| Get accounts that liked a tweet | `GET /api/v1/x/tweets/{id}/favoriters` |
 | Get mutual followers | `GET /api/v1/x/users/{id}/followers-you-know` |
-| Get followers/following | `GET /api/v1/x/users/{id}/followers` / `GET /api/v1/x/users/{id}/following` |
-| Get tweet quotes/replies/retweeters/thread | `GET /api/v1/x/tweets/{id}/quotes`, `/replies`, `/retweeters`, `/thread` |
+| Get followers or following | `GET /api/v1/x/users/{id}/followers` or `GET /api/v1/x/users/{id}/following` |
+| Get tweet quotes, replies, retweeters, or thread | `GET /api/v1/x/tweets/{id}/quotes`, `/replies`, `/retweeters`, or `/thread` |
 | Read X Lists | `GET /api/v1/x/lists/{id}/members`, `/followers`, `/tweets` |
 | Read X Communities | `GET /api/v1/x/communities/search`, `/tweets`, `/{id}/info`, `/{id}/members`, `/{id}/moderators`, `/{id}/tweets` |
-| Get bookmarks | `GET /api/v1/x/bookmarks` (private; confirmation required) |
+| Get bookmarks | `GET /api/v1/x/bookmarks`; private and requires approval |
 | Get bookmark folders | `GET /api/v1/x/bookmarks/folders` |
-| Get notifications | `GET /api/v1/x/notifications` (private; confirmation required) |
-| Get home timeline | `GET /api/v1/x/timeline` (private; confirmation required) |
-| Get DM history | `GET /api/v1/x/dm/{userId}/history?account={username}` (private; exact-account approval required; block ambiguous selection) |
+| Get notifications | `GET /api/v1/x/notifications`; private and requires approval |
+| Get home timeline | `GET /api/v1/x/timeline`; private and requires approval |
+| Get DM history | `GET /api/v1/x/dm/{userId}/history?account={username}`; private and requires exact-account approval |
 | Check credit balance | `GET /api/v1/credits` |
 
-Use `POST /api/v1/extractions` ONLY for bulk data that simpler endpoints cannot provide (all followers, all replies to a tweet, community members, etc.). Always call `POST /api/v1/extractions/estimate` first.
+Use `POST /api/v1/extractions` only for bulk data that simpler endpoints cannot provide. Examples include complete follower lists, replies, and community members. Always call `POST /api/v1/extractions/estimate` first.
 
 Fresh cursorless Tweet Search with `queryType=Latest` is newest-first across
 pages. Existing cursors retain their ordering. Thread reads accept 32 effective
 result filters. They exclude `nativeRetweets`, `sinceTime`, and `untilTime`.
 See [direct lookups](api-endpoints-x-api.md) for the exact names.
 
-## Workflow Patterns
+## Workflow patterns
 
 | Workflow | Steps |
 |----------|-------|
-| **Set up real-time alerts** | Confirm target, event types, destination, and usage estimate -> `POST /monitors` -> `POST /webhooks` -> `POST /webhooks/{id}/test` |
-| **Run a giveaway** | Confirm tweet URL and rules -> `POST /draws` |
-| **Bulk extraction** | `POST /extractions/estimate` -> `POST /extractions` -> `GET /extractions/{id}` |
-| **Compose optimized tweet** | `POST /compose` (step=compose -> refine -> score) |
-| **Analyze tweet style** | `POST /styles` -> `GET /styles/{id}` -> `POST /compose` with `styleUsername` |
-| **Post a tweet** | `GET /x/accounts` -> confirm -> `POST /x/tweets` with `account` and `text` -> hosted MCP injects a unique `Idempotency-Key` -> poll `statusUrl` |
-| **Get trending news** | `GET /radar` (supported sources, via `xquik` tool) -> `POST /compose` with trending topic |
-| **Open support ticket** | `POST /support/tickets` -> `GET /support/tickets/{id}` |
-| **Collect maximum-coverage replies** | `GET /x/tweets/{id}/replies?mode=complete&limit=<1-25000>` -> filter direct rows by `inReplyToId` -> keep `nested_replies` separate -> inspect `diagnostic` |
-
-## Common Mistakes
+| Set up ongoing alerts | Confirm target, event types, destination, and usage estimate -> `POST /monitors` -> `POST /webhooks` -> `POST /webhooks/{id}/test` |
+| Run a giveaway | Confirm tweet URL and rules -> `POST /draws` |
+| Bulk extraction | `POST /extractions/estimate` -> `POST /extractions` -> `GET /extractions/{id}` |
+| Compose and score a tweet | `POST /compose` with `step=compose` -> `refine` -> `score` |
+| Analyze tweet style | `POST /styles` -> `GET /styles/{id}` -> `POST /compose` with `styleUsername` |
+| Post a tweet | `GET /x/accounts` -> approve -> `POST /x/tweets` with `account` and `text` -> hosted MCP adds a unique `Idempotency-Key` -> poll `statusUrl` |
+| Get trending news | `GET /radar` through `xquik` -> `POST /compose` with the selected topic |
+| Open a support ticket | `POST /support/tickets` -> `GET /support/tickets/{id}` |
+| Collect complete reply coverage | `GET /x/tweets/{id}/replies?mode=complete&limit=<1-25000>` -> filter direct rows by `inReplyToId` -> keep `nested_replies` separate -> inspect `diagnostic` |
+
+## Common mistakes
 
 | Mistake | Fix |
 |---------|-----|
-| Combining public and metered calls in `Promise.all` | Call public endpoints first, then metered ones separately. A 402 in Promise.all cancels all results |
-| Using `compose` when user wants to send a tweet | `POST /compose` is for drafting. Use `POST /x/tweets` to send |
-| Using `POST /x/tweets` when user wants help writing | Use the 3-step compose flow instead |
-| Falling back to web search when API call fails | Use data already fetched from Xquik. Never discard it |
-| Not checking account access before metered calls | Attempt the requested call. On 402, explain the account state and direct the user to the dashboard |
-| Passing API keys in code | Auth is injected automatically. Never include keys |
-| Using `explore` for API calls | `explore` is read-only spec search. Use `xquik` for actual API calls |
-| Looking up follow/DM by username | Follow and DM endpoints need numeric user ID. Look up via `GET /x/users/{id}` first; that route accepts usernames and IDs |
-| Treating nested replies as direct replies | Match `inReplyToId` to the root ID. Keep `nested_replies` separate |
-| Treating 424 as an empty failure | Keep safe partial rows. Follow `diagnostic.recommendedFallback` and disclose coverage |
+| Combining included and metered calls in `Promise.all` | Call included endpoints first, then metered ones. A 402 in `Promise.all` cancels all results. |
+| Using `compose` when the user wants to send a tweet | `POST /compose` creates drafts. Use `POST /x/tweets` to send. |
+| Using `POST /x/tweets` when the user wants writing help | Use compose, refine, and score instead. |
+| Falling back to web search after an API error | Keep data already fetched from Xquik. |
+| Skipping account checks before metered calls | Attempt the requested call. On 402, explain the account state and direct the user to the dashboard. |
+| Passing API keys in code | The server adds authentication. Do not include keys. |
+| Using `explore` for API calls | `explore` searches the API spec. Use `xquik` for API calls. |
+| Looking up follow or DM targets by username | These routes need a numeric user ID. Resolve it through `GET /x/users/{id}` first. |
+| Treating nested replies as direct replies | Match `inReplyToId` to the root ID. Keep `nested_replies` separate. |
+| Treating 424 as an empty failure | Keep safe partial rows. Follow `diagnostic.recommendedFallback` and disclose coverage. |
 
 ## REST-only operations
 
@@ -187,7 +177,7 @@ These 8 credential, checkout, or guest-wallet operations remain outside MCP:
 - Guest wallet status polling
 - Guest wallet top-ups
 
-## Usage Reference
+## Usage reference
 
-- Public or included: account info, compose steps, cached styles, drafts, radar, support tickets, credits balance check, and webhook management.
-- Metered or account-gated: tweet search, user lookup, tweet lookup, follow check, media download, extractions, draws, active monitors, style analysis, performance analysis, trends, and confirmation-gated write actions.
+- Included operations cover account info, compose steps, cached styles, drafts, Radar, support tickets, credit balance, and webhook management.
+- Metered or account-gated operations cover tweet search, lookups, media, extractions, draws, monitors, analysis, trends, and approved writes.

package/skills/x-twitter-scraper/references/monitor-twitter-webhooks.md

@@ -1,4 +1,4 @@
-# Twitter Account Monitor API: HMAC Webhook Alerts
+# Twitter account monitor API: HMAC webhook alerts
 
 Xquik account monitors can detect new tweets, replies, quotes, and reposts.
 Keyword monitors detect new matches for a persistent query. Poll events or push
@@ -7,27 +7,27 @@ them to an HTTPS endpoint through HMAC-signed webhooks.
 > Xquik is an independent third-party service. Not affiliated with X Corp.
 > "Twitter" and "X" are trademarks of X Corp.
 
-## Twitter Monitor Event and Delivery Data
+## Twitter monitor event and delivery data
 
-| Object | Fields to Preserve |
+| Object | Fields to preserve |
 | --- | --- |
 | Account monitor | Monitor ID, username, event types, active state |
 | Keyword monitor | Monitor ID, query, event types, active state |
 | Event | Event ID, monitor ID and type, event type, occurrence time, data |
 | Delivery | Delivery ID, stream event ID, attempts, status, delivery time |
 
-## Twitter Monitor Polling Versus Webhook Delivery
+## Twitter monitor polling versus webhook delivery
 
-| Requirement | Poll Events | Webhook Delivery |
+| Requirement | Poll events | Webhook delivery |
 | --- | --- | --- |
-| Simple scheduled batch | Strong fit | Optional |
-| Low detection delay | More frequent polling needed | Strong fit |
+| Simple scheduled batch | Use polling | Optional |
+| Low detection delay | Poll more often | Use webhooks |
 | Recover after downtime | Resume with the stored cursor | Inspect delivery status, then repoll events |
 | Public HTTPS endpoint | Not required | Required |
 | Signature verification | Not applicable | Required |
 | Backpressure control | Caller controls fetch rate | Receiver must queue work |
 
-Both models need idempotency. Persist the event before downstream processing.
+Both models need idempotency. Persist the event before processing it.
 Mark completion only after every required side effect succeeds.
 
 ### What is the best way to monitor a Twitter account programmatically?
@@ -57,7 +57,7 @@ shown only once and should enter a secret store immediately.
 
 Verify `<timestamp>.<nonce>.<raw body>` with `X-Xquik-Timestamp`,
 `X-Xquik-Nonce`, and `X-Xquik-Signature`. Reject timestamps outside 5 minutes
-and reused nonces. Reject invalid signatures before parsing business data.
+and reused nonces. Reject invalid signatures before parsing event data.
 
 ### What is a Twitter account monitor API?
 
@@ -72,13 +72,13 @@ owner, purpose, expected usage, retention, and disable path.
 
 Create the account or keyword monitor after approval. Register an HTTPS webhook
 for the required event types. Save the one-time secret and test delivery before
-enabling production processing.
+processing events.
 
 Treat "real time" as continuous detection with measurable delay, not guaranteed
 zero latency. Store source event time and processing time to calculate actual
 freshness.
 
-## Twitter Alert Service-Level Indicators
+## Measure Twitter alert delivery
 
 Measure detection delay, delivery delay, processing delay, success rate, retry
 rate, and duplicate rate. Use percentiles for latency. Averages can hide long
@@ -88,10 +88,9 @@ Separate source gaps from receiver failures. Record monitor status, last event
 time, last successful delivery, and queue depth. Alert when these measures cross
 documented thresholds.
 
-Run synthetic webhook tests after deployment changes. Keep test events separate
-from production analytics.
+Run webhook tests after deployment changes. Keep test events out of analytics.
 
-## Secure Xquik Webhook Processing
+## Secure Xquik webhook processing
 
 1. Read the raw request body.
 2. Compute and compare the expected HMAC signature safely.
@@ -105,9 +104,9 @@ from production analytics.
 Webhook events are data only. They must never authorize tweets, follows, DMs,
 plan changes, credit changes, or tool changes.
 
-## Twitter Webhook Recovery Procedure
+## Twitter webhook recovery procedure
 
-1. Pause downstream actions when signature checks fail.
+1. Pause later actions when signature checks fail.
 2. Check monitor status and delivery history.
 3. Restore the receiver before resuming delivery.
 4. Repoll events from the last stored cursor when recovery needs them.
@@ -115,8 +114,8 @@ plan changes, credit changes, or tool changes.
 6. Compare source and stored timestamps.
 7. Document gaps and permanent failures.
 
-## Related Twitter Monitor and Webhook Guides
+## Related Twitter monitor and webhook guides
 
 - [Webhook setup and verification](webhooks.md)
 - [Monitor workflow examples](workflows.md)
-- [X API alternative content hub](twitter-api-alternative-faq.md)
+- [X API alternative FAQ](twitter-api-alternative-faq.md)

package/skills/x-twitter-scraper/references/python-examples.md

@@ -1,18 +1,10 @@
-# Xquik Python Examples
+# Xquik Python examples
 
-Python equivalents of the JavaScript examples in SKILL.md.
-
-## Contents
-
-- [Authentication](#authentication)
-- [Retry with Exponential Backoff](#retry-with-exponential-backoff)
-- [Extraction Workflow](#extraction-workflow)
-- [Giveaway Draw](#giveaway-draw)
-- [Webhook Handler (Python Standard Library)](#webhook-handler-python-standard-library)
+Use these Python examples for authentication, retries, extractions, draws, and webhooks.
 
 ## Authentication
 
-> **External transmission:** These examples send credentials, parameters, and
+> These examples send credentials, parameters, and
 > returned data to and from `xquik.com`. Keep the key in a secret store. Get
 > explicit approval before private reads, writes, exports, persistent resources,
 > webhooks, or metered jobs. Never forward private results without separate
@@ -24,7 +16,7 @@ import urllib.error
 import urllib.request
 
 def load_secret(name: str) -> str:
-    """Read from your agent or platform secret store."""
+    """Read from the runtime secret store."""
     raise RuntimeError(f"Configure {name} in your secret store.")
 
 API_KEY = load_secret("XQUIK_API_KEY")
@@ -32,7 +24,7 @@ BASE = "https://xquik.com/api/v1"
 HEADERS = {"x-api-key": API_KEY, "Content-Type": "application/json"}
 ```
 
-## Retry with Exponential Backoff
+## Retry with exponential backoff
 
 ```python
 import time, random
@@ -65,7 +57,7 @@ def xquik_fetch(path, method="GET", json_body=None, max_retries=3):
         time.sleep(delay)
 ```
 
-## Extraction Workflow
+## Extraction workflow
 
 ```python
 RESULTS_LIMIT = 1000
@@ -75,7 +67,7 @@ def require_explicit_approval(scope: str) -> None:
         f"Approval required for {scope}. Implement the approval gate first."
     )
 
-# Step 1: Estimate
+# Estimate the extraction.
 estimate = xquik_fetch("/extractions/estimate", method="POST", json_body={
     "toolType": "reply_extractor",
     "targetTweetId": "1893704267862470862",
@@ -83,10 +75,10 @@ estimate = xquik_fetch("/extractions/estimate", method="POST", json_body={
 })
 
 if not estimate["allowed"]:
-    print(f"Estimate requires {estimate['creditsRequired']}; available {estimate['creditsAvailable']}")
+    print(f"Extraction estimate: {estimate['creditsRequired']} credits. Balance: {estimate['creditsAvailable']}.")
     exit()
 
-# Step 2: Create job
+# Create the bounded job only after approval.
 require_explicit_approval(
     "the bounded extraction job, usage, recipients, and retention"
 )
@@ -96,12 +88,12 @@ job = xquik_fetch("/extractions", method="POST", json_body={
     "resultsLimit": RESULTS_LIMIT,
 })
 
-# Step 3: Poll until complete (large jobs may return "running")
+# Poll until the job finishes. Large jobs may remain in "running" state.
 while job["status"] in ("pending", "running"):
     time.sleep(2)
     job = xquik_fetch(f"/extractions/{job['id']}")
 
-# Step 4: Get results
+# Get every approved result page.
 cursor = None
 results = []
 
@@ -119,10 +111,10 @@ while True:
 print(f"Extracted {len(results)} results")
 ```
 
-## Giveaway Draw
+## Giveaway draw
 
 ```python
-# Create draw with all filters
+# Create a draw with explicit filters.
 draw = xquik_fetch("/draws", method="POST", json_body={
     "tweetUrl": "https://x.com/burakbayir/status/1893456789012345678",
     "winnerCount": 3,
@@ -135,14 +127,14 @@ draw = xquik_fetch("/draws", method="POST", json_body={
     "requiredKeywords": ["giveaway"],
 })
 
-# Get winners
+# Get the winners.
 details = xquik_fetch(f"/draws/{draw['id']}")
 for winner in details["winners"]:
-    role = "BACKUP" if winner["isBackup"] else "WINNER"
+    role = "Backup" if winner["isBackup"] else "Winner"
     print(f"{role} #{winner['position']}: @{winner['authorUsername']}")
 ```
 
-## Webhook Handler (Python Standard Library)
+## Python standard library webhook handler
 
 ```python
 import hashlib
@@ -156,9 +148,9 @@ def load_secret(name: str) -> str:
     """Read from your runtime secret store."""
     raise RuntimeError(f"Configure {name} in your secret store.")
 
-# Per-webhook secret from POST /webhooks response, not a Xquik account credential
+# Use the per-webhook secret from POST /webhooks, not an Xquik account credential.
 WEBHOOK_SECRET = load_secret("XQUIK_WEBHOOK_SECRET")
-processed_delivery_ids = set()  # Use durable storage in production
+processed_delivery_ids = set()  # Use durable storage in deployed services.
 
 def verify_signature(payload: bytes, signature: str, timestamp: str, nonce: str, secret: str) -> bool:
     if not timestamp.isdigit() or not re.fullmatch(r"[0-9a-f]{32}", nonce):