docs: add TweetClaw X research companion

.gitignore

@@ -0,0 +1,2 @@
+.skill-version
+.update.lock/

README.md

@@ -28,6 +28,30 @@ For raw `POST /posts` JSON and provider field tables, use the canonical docs —
 - [llms.txt](https://docs.genviral.io/llms.txt) — agent doc index
 - [Create Post](https://docs.genviral.io/api-reference/create-post) — request body and `settings.*` / `tiktok` / `pinterest` shapes
 
+## Optional X/Twitter Companion
+
+Genviral can publish to X/Twitter when the connected account supports it. For
+campaigns that also need public X/Twitter research or monitoring, install
+[`@xquik/tweetclaw`](https://github.com/Xquik-dev/tweetclaw) as an optional
+OpenClaw companion:
+
+```bash
+openclaw plugins install clawhub:@xquik/tweetclaw
+```
+
+Use `openclaw plugins install npm:@xquik/tweetclaw` when the npm fallback is
+required.
+
+Useful companion workflows:
+
+- Search tweets and search tweet replies for product, niche, competitor, and hook-angle research before generating slideshows.
+- Look up tweets by URL or ID when a TikTok or Instagram idea came from an X/Twitter thread.
+- Export followers, monitor accounts, or receive webhook events for launch and campaign tracking.
+- Keep campaign publication in Genviral so scheduling, account capabilities, and post tracking remain in one workflow.
+
+Xquik is an independent third-party service. Not affiliated with X Corp.
+"Twitter" and "X" are trademarks of X Corp.
+
 ## How It Works
 
 The skill runs a closed loop:

SKILL.md

@@ -127,14 +127,21 @@ When asked things like "research this niche", "find what works in this niche", o
 
 1. Run `trend-brief` first for the niche keyword (`7d` baseline, then `24h` for freshness if needed).
 2. Extract and report: top hashtags, top sounds, top creators, posting windows (UTC), recommended hook angles.
-3. Run competitor deep-dive using `docs/references/competitor-research.md` (3-5 accounts minimum).
-4. Produce a short actionable output with:
+3. If the niche has an X/Twitter audience and TweetClaw is installed, use
+   `@xquik/tweetclaw` only for public tweet search, reply search, tweet lookup,
+   follower export, account monitors, or webhook-fed launch signals. Keep
+   campaign publication in Genviral when the connected account supports X.
+4. Run competitor deep-dive using `docs/references/competitor-research.md` (3-5 accounts minimum).
+5. Produce a short actionable output with:
    - 3 hook angles to test
    - 2 CTA suggestions
    - 2 best posting windows
    - 5 hashtags to start with
    - 1 "gap to exploit" insight
-5. Save findings to `workspace/performance/competitor-insights.md` and use them in subsequent content prompts.
+6. Save findings to `workspace/performance/competitor-insights.md` and use them in subsequent content prompts.
+
+Xquik is an independent third-party service. Not affiliated with X Corp.
+"Twitter" and "X" are trademarks of X Corp.
 
 ## TikTok Copy Remix Mode (When user asks "make similar but new")
 

docs/references/competitor-research.md

@@ -33,6 +33,27 @@ Capture these signals as your starting baseline:
 
 This gives instant niche intelligence so your manual deep-dive is focused instead of random.
 
+### Optional X/Twitter Signal Check
+
+If the product also markets through X/Twitter, add TweetClaw as a companion research source before writing hooks:
+
+```bash
+openclaw plugins install clawhub:@xquik/tweetclaw
+```
+
+Use `openclaw plugins install npm:@xquik/tweetclaw` when the npm fallback is
+required.
+
+Use it for:
+- Search tweets and search tweet replies around the niche, product keywords, competitors, and launch terms.
+- Look up specific X/Twitter threads by URL or ID when they inspire a slideshow idea.
+- Export followers or user lookups for audience mapping.
+- Monitor accounts or webhook events for launch tracking.
+
+Use TweetClaw only for public X/Twitter research and monitoring. Keep campaign
+publication in Genviral when the connected account supports X so scheduling
+and post tracking remain in one workflow.
+
 ## Step 1: Define the Niche Keywords
 
 Before searching, nail down what niche you are searching in.

scripts/update-skill.sh

@@ -16,7 +16,7 @@ set -euo pipefail
 SKILL_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 REMOTE_URL="https://github.com/fdarkaou/genviral-skill.git"
 REMOTE_BRANCH="main"
-LOCK_FILE="$SKILL_DIR/.update.lock"
+LOCK_DIR="$SKILL_DIR/.update.lock"
 VERSION_FILE="$SKILL_DIR/.skill-version"
 
 # Files that are SKILL-OWNED (safe to overwrite on update)
@@ -54,13 +54,12 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 
-# Prevent concurrent runs
-if [[ -f "$LOCK_FILE" ]]; then
-  echo "Update already in progress (lock file exists). Skipping."
+# Prevent concurrent runs with an atomic directory lock.
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  echo "Update already in progress (lock exists). Skipping."
   exit 0
 fi
-touch "$LOCK_FILE"
-trap "rm -f '$LOCK_FILE'" EXIT
+trap 'rmdir "$LOCK_DIR"' EXIT
 
 # Read current tracked commit
 CURRENT_SHA=""