Search for external mentions. X/Twitter is fetched via the X.AI Responses API (primary); the rest of the public web (Reddit, Farcaster, blogs, newsletters, GitHub Discussions, HN, Product Hunt) goes through WebSearch, which is also the last-resort fallback for X itself. Derive the operator's handle from soul/SOUL.md if present (call it $OPERATOR) so you can exclude their own posts.
Path A - X.AI API (primary, X/Twitter mentions). For each target, ask Grok's x_search who is talking about the project on X. See the Fetching contract below - attempt this whenever the key is present, set the Bash tool timeout to ≥180000, and capture the HTTP status. Use a unique tmp filename per target if you loop (e.g. /tmp/xai-mr-$SLUG.json). $NAME/$DOMAIN/$REPO come from the target built in step 1 ($DOMAIN/$REPO may be empty - leave them out if so):
FROM_DATE=$(date -u -d "7 days ago" +%Y-%m-%d 2>/dev/null || date -u -v-7d +%Y-%m-%d)
TO_DATE=$(date -u +%Y-%m-%d)
PROMPT="Search X for posts by OTHER people mentioning the project \"${NAME}\" (also its site ${DOMAIN} and repo ${REPO} when given), posted between ${FROM_DATE} and ${TO_DATE}. Exclude posts by the operator @${OPERATOR} and by the project's own accounts. For each mention return: @handle, the full post text, date, exact engagement counts (likes, retweets, replies; 0 if unknown), the poster's approximate follower count if visible, and the direct link https://x.com/handle/status/ID. Prioritize people discovering it for the first time, asking confused questions, hitting friction (setup/docs/missing feature), comparing it to a competitor, or requesting a feature. Return a numbered list; if nobody is talking about it, say so explicitly."
jq -n --arg p "$PROMPT" --arg fd "$FROM_DATE" --arg td "$TO_DATE" \
'{model:"grok-4-1-fast", input:[{role:"user",content:$p}], tools:[{type:"x_search",from_date:$fd,to_date:$td}]}' \
> /tmp/xai-mr-payload.json
HTTP=$(./secretcurl -s -o /tmp/xai-mr.json -w '%{http_code}' --max-time 150 -X POST "https://api.x.ai/v1/responses" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {XAI_API_KEY}" \
-d @/tmp/xai-mr-payload.json)
echo "xai http=$HTTP bytes=$(wc -c </tmp/xai-mr.json)"
On HTTP=200 with a non-empty body, parse /tmp/xai-mr.json with jq -r '.output[] | select(.type == "message") | .content[] | select(.type == "output_text") | .text' and feed the X mentions into categorization (step 4). Record X_SOURCE=api.
Path B - WebSearch (broader web + X fallback). Always use WebSearch for the non-X surfaces - Reddit, Farcaster, personal blogs, newsletters, GitHub Discussions, HN, Product Hunt:
- Try both brand name and URL variants
- Time-box to last 7 days where the search engine supports it
- Skip results from the operator's own accounts and the project's own repos
WebSearch is also the fallback for X/Twitter, but only when Path A truly failed (key-unset, http-<code>, empty, or timeout - record the real reason per the Fetching contract, never "XAI_API_KEY unavailable" when the key was set). On the X fallback query site:x.com "<project name>" after:${FROM_DATE}; note in the log that X results came from WebSearch (lower quality) and set X_SOURCE=websearch.
