VVVLINK Site Builder

VVVLink Sitebuilder

Use this skill when the user wants to create, redesign, or publish a website, landing page, portfolio, or any HTML page that should be accessible online.

Before ANY work, announce to the user: "Using vvvlink-site-builder to create and publish your site."

Quick Reference

VVVLink Site Builder
Your sites:
1. my-site.vvvlink.com
2. cool-page.vvvlink.com
+2 drafts (uploading). Ask me to show or clean them up.
I can update any of these or create a new one.
What would you like to do?

VVVLink Site Builder
I build and publish websites on vvvlink.com in seconds.
Describe what you need — a landing page, portfolio,
business site — and I'll design, build, and publish it.
Your site will be live with a unique URL right away.

⚡ Building your site with VVVLink Site Builder...
🔍 Searching for photos of [topic]...
[tool call: curl image search]
📸 Found 5 great shots!
🎨 Designing layout with [palette] and [fonts]...
🏗️ Building hero section...
[tool call: write first part of HTML]
✨ Adding content sections...
[tool call: write rest of HTML]
📦 HTML ready!
🚀 Publishing to vvvlink.com...
[tool call: create site]
[tool call: upload file]
[tool call: publish]
[tool call: rename subdomain]
✅ Your site is live!
🌐 https://your-site.vvvlink.com

IMPORTANT: These progress rules apply ONLY when BUILDING a site (multi-step process: photos → HTML → upload → publish). For simple operations like listing sites or checking status — just do it quickly, no need for multiple progress messages. One short message before + result is enough.

Step 1.5: Ask for business details (if missing)

If the site looks like a business page (cafe, shop, studio, agency, etc.) and the user did NOT provide key info, gently ask ONCE before building. Keep it short — one message:

"📋 Before I start — want to add any of these to make it real? 📞 Phone / email / address 🕐 Opening hours 🔗 Social media links

Or I can build it now and you'll add details later."

If user says "just build it" or similar — proceed immediately. Do NOT block the build. This is optional, not a gate. Skip this step entirely for non-business sites (portfolios, personal pages, experiments).

Step 2: Find photos for the site

Before writing any code, search for relevant photos:

# Search by keywords matching the site's topic
curl -s "https://publish.vvvlink.com/images/search?q=KEYWORD&count=5&orientation=landscape"

Pick 3-6 keywords based on the site content (e.g., "office", "team", "technology"). Select the best photo for each section (hero, about, features, etc.). Use the url field from the response directly in tags.

Add &w=1600&h=900&fit=crop to URLs for hero images, &w=600&h=400&fit=crop for cards.

Step 3: Create the site

Read and follow references/website-development-rules.md. Build a high-quality static site using the photos from Step 2. Output all files to ~/.vvvlink/sites//.

Step 4: Get API key

apiKey is SECRET. Never show it to the user, never log it, never include in messages. It is only for Authorization headers.

UUID is public. It identifies the account. You may show it to the user if asked.

Storage: ~/.vvvlink/config.json

{
  "uuid": "account-uuid",
  "apiKey": "SECRET-key-never-share"
}

Site files: ~/.vvvlink/sites//

Rules: 1. NEVER call /auth/create_new_user if ~/.vvvlink/config.json exists. The apiKey is issued ONCE and cannot be recovered. 2. Only create a new account if config.json does not exist. 3. Protect ~/.vvvlink/config.json with chmod 600.

Procedure: 1. Read ~/.vvvlink/config.json → use .apiKey 2. If file does not exist → POST /auth/create_new_user {} → save response to config.json

# Load or create API credentials
VVVLINK_DIR="$HOME/.vvvlink"
VVVLINK_CONFIG="$VVVLINK_DIR/config.json"
if [ -f "$VVVLINK_CONFIG" ]; then
  VVVLINK_API_KEY=$(jq -r '.apiKey' "$VVVLINK_CONFIG")
else
  mkdir -p "$VVVLINK_DIR"
  RESP=$(curl -s -X POST https://publish.vvvlink.com/auth/create_new_user \
    -H "Content-Type: application/json" -d '{}')
  if echo "$RESP" | jq -e '.apiKey' > /dev/null 2>&1; then
    VVVLINK_API_KEY=$(echo "$RESP" | jq -r '.apiKey')
    echo "$RESP" | jq '{uuid: .uuid, apiKey: .apiKey}' \
      > "$VVVLINK_CONFIG"
    chmod 600 "$VVVLINK_CONFIG"
  else
    echo "Error: could not create account" >&2
    exit 1
  fi
fi

Step 5: Create site and upload

# Create site
curl -s -X POST https://publish.vvvlink.com/sites \
  -H "Authorization: Bearer $API_KEY"
Upload each file (from ~/.vvvlink/sites//)
curl -s -X PUT \
  "https://publish.vvvlink.com/sites/$SITE_ID/files/index.html" \
  -H "Authorization: Bearer $API_KEY" \
  --data-binary @~/.vvvlink/sites/$SUBDOMAIN/index.html

Upload ALL files: HTML, CSS, JS, images, fonts.

If POST /sites returns HTTP 429 with "Site limit reached", the user has hit their plan limit. Handle this gracefully:

1. Call the upgrade endpoint to get a checkout URL:

curl -s -X POST https://publish.vvvlink.com/billing/upgrade \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"success_url": "https://vvvlink.com"}'

2. Show the user an upgrade message with the payment link. In Telegram, use an inline link so the user can pay in the built-in web view:

⚠️ *Site limit reached*
You've used all available sites on the Free plan\.
🚀 Upgrade to Pro to unlock up to 100 sites\.
_After upgrading, I'll publish your site right away\._

3. After the user pays and confirms, retry POST /sites. The limit will be updated automatically.

If the upgrade endpoint returns "Already on Pro plan", the user is already on Pro — this means they've genuinely used all 100 sites. Tell them to delete unused sites first.

Step 6: Publish

curl -s -X POST \
  "https://publish.vvvlink.com/sites/$SITE_ID/publish" \
  -H "Authorization: Bearer $API_KEY"

Step 7: Choose subdomain BEFORE creating site

Do NOT create a site with a random name. Pick a good one first:

1. Analyze the site content (