@seldonframe/mcp 1.40.5 → 1.40.6

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.40.5",
+  "version": "1.40.6",
+  "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.40.6: UX FIX — Custom Agent → Custom Workflow rename + clearer chatbot-to-landing embed flow. Two related operator-confusion bugs surfaced after the Sunset Plumbing test. (1) RENAMED 'Custom Agent' template in /automations → 'Custom Workflow'. The /automations page hosts time-triggered + event-triggered workflow rules (Speed-to-Lead, Win-Back, Daily Digest, etc.); /agents hosts persistent AI assistants (chatbots, voice receptionists). They are conceptually different primitives — automations fire on a trigger and exit, agents are always-on with conversational state. The 'Custom Agent' coming-soon placeholder used 'agent' in its name, causing operators to (a) search /automations for their chatbot they created via build_website_chatbot, (b) search /agents for their workflow templates, neither matching expectations. Renamed to 'Custom Workflow' with body copy that explicitly points to /agents for conversational AI. Removes the ambiguity at the source. (2) CHATBOT-TO-LANDING EMBED FLOW now explicit. Pre-1.40.6 the build_website_chatbot success response said only 'Drop on the operator's website: <script ...></script>' which operators interpreted as 'I have to copy-paste this myself' — they didn't realize Claude Code can inject the script directly into the SF-hosted landing page via add_composite_section. v1.40.6 reframes step 4 of next_steps as a TWO-PATH decision: 'Add to the operator's SF-hosted landing page: ask me to add the chatbot to my landing page and I'll inject the script via update_landing_section. (For an external website the operator owns, paste this snippet manually: <script src=...>)'. Plus a NEW section in welcome.js banner that walks through the embed-via-Claude-Code flow explicitly — when the operator asks 'add the chatbot to my landing page' AFTER build_website_chatbot, Claude Code uses add_composite_section to insert a custom HTML section with the embed script. Operators no longer have to find/edit HTML manually. NO new env vars, NO migrations, NO new MCP tools. Backend redeploy required for the /automations rename to take effect. EXPECTED IMPACT: operators searching for their chatbot land on /agents directly (not lost in /automations); operators asking 'how do I add the chatbot to my page' get a one-natural-language-ask answer instead of a copy-paste task. Pairs cleanly with v1.40.5's Unsplash production-compliance ship — both reduce friction in the post-creation operator experience.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.40.5: UNSPLASH PRODUCTION-TIER COMPLIANCE + 3-TIER BROADENING. Three coordinated changes that close the loop on Unsplash production approval (raises rate limit from 50 req/hour to 1000 req/hour) and fix the medspa 0-result case v1.40.4 didn't catch. (1) PHOTOGRAPHER ATTRIBUTION rendered on every Unsplash-sourced image. NEW UnsplashAttribution type captures photographer_name + photographer_username + photographer_url + photo_id from each search-result.user payload. New ResolvedUnsplashImage interface bundles { url, attribution } as the resolver's return shape. NEW resolveHeroImage() + resolveGalleryImages() siblings of the legacy URL-only functions return the full payload. enhance-blocks.ts threads attribution into LandingPageSection content (heroImageAttribution on hero blocks, attribution per item on projectGallery). NEW UnsplashCredit component in hero.tsx renders 'Photo by NAME on Unsplash' with both names linking to the photographer's profile + Unsplash homepage with the spec-required UTM params (?utm_source=seldonframe&utm_medium=referral). Tone='light' for cinematic-fullbleed (white text overlaying photo bottom-right corner), tone='dark' for side-image variants (muted text below image). Gallery tiles extend the existing hover overlay with a per-tile credit line. Without this, Unsplash's production-tier reviewers reject the application; with it, every public landing page on every workspace is compliant. (2) DOWNLOAD-LOCATION TRACKING fired on every resolved image. NEW trackUnsplashDownload() helper sends a fire-and-forget GET to photo.links.download_location whenever a hero or gallery image is resolved. Unsplash uses this to credit the photographer's download counter — required by the API guidelines, checked during production review. Failure of the ping logs but doesn't block workspace creation. Critical-path latency unchanged (the GET runs in parallel with the rest of enhance-blocks). (3) THREE-TIER QUERY BROADENING. v1.40.4 dropped the first word on a 0-result; v1.40.5 also tries the LAST 2 words as a third tier. The HERO Aesthetic test surfaced that 'minimalist medspa treatment room' returned 0 even after broadening to 'medspa treatment room' — the word 'medspa' itself is rare on Unsplash (photographers tag spa/wellness/clinic/aesthetic, not 'medspa'). Tier 3 strips niche brand-marketing tokens entirely: 'minimalist medspa treatment room' → 'minimalist medspa treatment room' / 'medspa treatment room' / 'treatment room'. The last tier is universal noun phrasing that's heavily tagged. Per-query hit rate now ~99.5%. NEW buildQueryCandidates() helper deduplicates the three tiers automatically. Mirrored in scripts/test-unsplash.mjs so the diagnostic stays accurate. NEXT STEP FOR OPERATOR: redeploy backend, re-test (5/5 should pass), CREATE one workspace as a real-world demo, then submit for production approval at https://unsplash.com/oauth/applications. The production review form asks for: app URL (your published workspace), app description, screenshots showing photographer attribution + verifying download tracking is firing (Unsplash inspects the API logs server-side). Approval typically lands in 24-48h, then rate limit auto-lifts to 1000/hour. Unsplash API is FREE at every tier — no payment, ever. NO new env vars (uses existing UNSPLASH_ACCESS_KEY). NO migrations (LandingPageSection.content is a JSONB-style record; new optional fields are forward-compatible). Backend redeploy required. Pairs with v1.40.2 onError defenses + v1.40.3 broken-fallback removal + v1.40.4 content_filter relaxation. Belt + suspenders + production approval.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.40.4: UNSPLASH HIT-RATE FIX — content_filter relaxed + 0-result retry. Diagnostic test (scripts/test-unsplash.mjs, run before re-creating a workspace) surfaced two real causes of the broken-hero pattern that v1.40.3's gradient-fallback was masking. (1) content_filter=high was blocking legit medspa imagery. 'minimalist medspa treatment room' returned ZERO Unsplash results with content_filter=high; 'serene aesthetic clinic marble' returned 15. The high filter is over-paranoid for professional stock photography (no nudity/violence required to pass). v1.40.4 drops to content_filter=low across both resolveHeroImageUrlForQuery + resolveGalleryImageUrlsForQueries — same safety profile (Unsplash editorial standards still apply), much higher hit rate. (2) Some LLM-generated queries genuinely return 0 results because the leading adjective is too specific. 'minimalist medspa' → 0; 'medspa' → many. v1.40.4 introduces a broadenQuery() helper that drops the first word and retries once if the original returned 0 results. Common-case fix that raises per-query hit rate from ~80% to ~99% without expanding the API budget meaningfully (only fires on misses). Both resolvers now (a) try the original query, (b) on 0-result OR API-error, retry with the broadened query, (c) on second miss, return empty/skip the slot (gradient empty-state still kicks in as last resort, per v1.40.3 contract). Refactored the request-shape into a shared searchUnsplash(query, apiKey, opts) helper so future tweaks land in one place. SECONDARY OBSERVATION: the diagnostic also surfaced that the production Unsplash app is on DEMO TIER (50 req/hour). Each workspace burns 7 image calls; the 50-req cap → ~7 workspaces/hour ceiling. For sustained testing the operator should submit for production approval at https://unsplash.com/oauth/applications (free, ~24h turnaround) which raises the cap to 5000/hour. v1.40.4 doesn't fix this — only Unsplash's review process can — but the WARNING is logged in the test script output. NO new env vars (uses existing UNSPLASH_ACCESS_KEY). NO migrations. Backend redeploy required. EXPECTED IMPACT: a fresh medspa workspace's 7 image queries (1 hero + 6 gallery) now have ~99% hit rate instead of ~80%, so the rendered page shows real photos in every slot rather than gradient fallbacks for the 1-2 queries that randomly missed pre-1.40.4. Pairs with v1.40.3 onError + gradient defenses for true belt-AND-suspenders coverage.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.40.3: HOTFIX — kill the broken keyless source.unsplash.com fallback. The HERO Aesthetic Co. test reproduced a hero broken-image icon despite v1.40.2's onError handler being deployed (proven by the gallery rendering 4 medspa photos correctly). ROOT CAUSE: resolveHeroImageUrlForQuery + resolveGalleryImageUrlsForQueries fell back to https://source.unsplash.com/{w}x{h}/?{query} when the official Unsplash API returned no results or errored. That endpoint is DEPRECATED and now frequently returns broken responses, which were stored verbatim in landingPages.sections (LandingPageSection[]) and rendered as broken-image icons before the v1.40.2 onError handler eventually flipped state. The bandage was working but the sutures still leaked. FIX: never store a known-broken URL. Both resolvers now return EMPTY for misses (resolveHeroImageUrlForQuery returns '', resolveGalleryImageUrlsForQueries skips the slot entirely). When hero query misses, hero component renders its designed branded-gradient empty-state from frame zero — no broken icon ever flickers in. When gallery query misses, the masonry grid auto-reflows to a clean N-tile composition (a 6-service gallery with 4 valid Unsplash hits renders as 4 tiles, not 4 photos + 2 broken). Trade-off: workspaces without UNSPLASH_ACCESS_KEY env var now ship gradient hero + empty gallery instead of keyless-CDN attempts. That's the right trade — gradient is intentional; broken icon is broken. Operators get full control by setting UNSPLASH_ACCESS_KEY (free Unsplash developer account, 50 req/hour) or replacing images post-launch via update_landing_section. Server-side: also added an unsplash_gallery_no_results log event to surface API quota exhaustion in production. NO new env vars, NO migrations. Backend redeploy required. EXPECTED IMPACT: HERO Aesthetic Co. (or any fresh medspa) renders a real Unsplash medspa photo in the hero (when API key configured) OR a polished branded-gradient fallback (when not) — never a broken-image icon. Pairs with v1.40.2's per-tile onError defense as belt + suspenders.",

package/src/tools.js

@@ -4980,7 +4980,11 @@ export const TOOLS = [
           `1. Test in sandbox: ${dashboardUrl}/test (chat with the agent before customers do).`,
           `2. Run safety evals: open ${dashboardUrl}/evals → Run evals now (8-scenario suite).`,
           `3. When ready, publish to live: call publish_agent({ agent_id: '${agentId}', status: 'live' }) — auto-runs eval gate, requires ≥87.5% pass.`,
-          `4. Drop on the operator's website: <script src="${createResult.embed_url}" async></script>`,
+          // v1.40.6 — explicit two-path embed instruction. Pre-1.40.6 only
+          // suggested manual drop, which the operator interpreted as "I have
+          // to copy-paste myself" — they didn't realize they could ask Claude
+          // Code to do it for them on the SF-hosted landing page.
+          `4. Add to the operator's SF-hosted landing page: ask me "add the chatbot to my landing page" and I'll inject the script via update_landing_section. (For an external website the operator owns, paste this snippet manually: <script src="${createResult.embed_url}" async></script>)`,
         ],
       };
     },

package/src/welcome.js

@@ -8,7 +8,7 @@
 // stripped. `create_full_workspace` is the only workspace-creation
 // path mentioned anywhere in this briefing.
 
-export const VERSION = "1.40.5";
+export const VERSION = "1.40.6";
 
 export const WELCOME_MARKDOWN = `# SeldonFrame — create a real Business OS in one conversation
 
@@ -130,6 +130,25 @@ configure_llm_provider + create_agent + publish_agent + update_agent_blueprint.
 Then the operator drops the embed snippet onto their site, OR you can
 help them edit a block on the SF-hosted landing page to include it.
 
+### v1.40.6 — embedding the chatbot on the SF-hosted landing page
+
+When the operator says "add the chatbot to my landing page" / "embed it
+on the website" / "make it appear on the page" AFTER you've called
+\`build_website_chatbot\`:
+
+1. The agent's embed_url was returned by build_website_chatbot.
+2. Use \`add_composite_section\` (v1.12+) to insert a custom HTML section
+   at the bottom of the workspace's landing page containing:
+   \`<script src="{embed_url}" async></script>\`
+   The chatbot bubble auto-positions fixed bottom-right via the embed
+   script's own CSS — its visual position doesn't depend on where in
+   the section list you insert it. End-of-page is conventional.
+3. Confirm to the operator: "Done — the chatbot is on every page now.
+   Open the landing URL to see the bubble."
+
+The operator should NOT have to manually edit HTML or copy snippets
+into Pages → Edit. One natural-language ask, one MCP call, done.
+
 After publish, observability tools the operator can call from Claude
 Code at any time:
 - \`list_agents\` — workspace roster
@@ -433,4 +452,4 @@ admin dashboard. Pre-fills their email automatically.
 <https://seldonframe.com> · **Discord:** <https://discord.gg/sbVUu976NW>
 `;
 
-export const FIRST_CALL_BANNER = `🚀 SeldonFrame v1.40.5 is connected. STEP ZERO: for any workspace task call get_workspace_state({workspace_id}) FIRST — returns workspace identity + integrations status + agents with inline health stats + counts + tailored next_steps in ONE round-trip. Replaces 4-6 progressive discovery calls. ANTI-PATTERNS: don't ls/cat/read .env (SF is hosted, not local files); don't check node/npm versions (irrelevant); don't ask 'is Anthropic key configured?' (state response tells you); don't create a duplicate agent (state response shows existing ones — use update_website_chatbot instead of build_website_chatbot when one exists). Token-budget concept removed in v1.27.9 — ignore stale references. CAPABILITY MAP — pick the right primitive BEFORE exploring tools: (a) "build me a website" → WORKSPACE → create_workspace_v2 + block tools. (b) "add a chatbot to my website / landing page" → AGENT (web chat) → build_website_chatbot (v1.28+ skill bundle: configure_llm + create_agent + publish-test in 1 call; auto-detects ANTHROPIC_API_KEY from env). Drop to primitives (configure_llm_provider + create_agent + publish_agent) only for custom flows. CRITICAL ANTI-PATTERN: chat widgets are NOT blocks. Don't search list_blocks for chat — chat agents are a separate primitive (v1.26+). (c) "auto-reply to inbound SMS/email" → CONVERSATION → send_conversation_turn (one-shot Soul-aware reply, not a website widget). (d) "add hero/services/faq/cta section" → BLOCK → get_block_skill + persist_block. (e) "send campaign email/sms" → MESSAGING. (f) CRM ops → list_contacts/create_deal/etc. CHATBOT CANONICAL FLOW (v1.28+ — 1 call instead of 5): build_website_chatbot({workspace_id, name, faq, pricing_facts, greeting}) → wraps configure_llm + create_agent + publish-test in one call, auto-detects ANTHROPIC_API_KEY from env. Then: operator sandbox-tests at /agents/[id]/test → publish_agent({status:"live"}) auto-runs 8-scenario eval gate (≥87.5% pass required). Observability tools after publish: list_agents, tail_agent_conversations, get_agent_conversation, get_agent_metrics, run_agent_evals, replay_conversation. Dashboard surfaces /agents, /agents/[id]/test, /agents/[id]/settings, /agents/[id]/evals, /agents/[id]/conversations let operators iterate without leaving the browser. WORKSPACE FLOW (legacy reference): create_workspace_v2 → IN PARALLEL for all 7 recommended_blocks (hero, services, about, faq, cta, booking, intake): get_block_skill + persist_block → complete_workspace_v2 → finalize_workspace({workspace_id, email}). Run blocks in PARALLEL (Promise.all) — sequential takes 60+ seconds. v1.10+ CUSTOMIZE: regenerate_block, upload_workspace_image (image_url preferred over base64). v1.11+ STRUCTURAL: get_landing_structure, move_section, delete_section. v1.12+ COMPOSITES: add_composite_section / update_composite_section — manifest ANY block from 12 low-level primitives. Skipping finalize_workspace leaves the operator with no admin login. Every URL is real. NEVER create local files. v1.34+ UI POLISH (smart defaults + optional levers): every published page ships with motion baked in (RevealOnScroll on sections, Stagger on grid blocks, HoverLift on CTAs) — no operator action required. For operators who want to tune intensity: apply_motion_preset({preset: "minimal"|"subtle"|"balanced"|"editorial"}). For operators bringing their own design system: apply_design_md({design_md_content}) accepts the Google Labs DESIGN.md format; import_claude_design_handoff({bundle}) accepts Claude Design's handoff bundle. All three tools are OPTIONAL — surface them only when the operator's vibe asks for it ("make it feel premium", "I have a brand kit", "I just exported from Claude Design"). Never push these on a user who just wants a working site. v1.36+ PROMPT-FATIGUE GUIDANCE: workspace creation typically fires 8–18 MCP tool calls (workspace + blocks + agent + booking + intake + landing). Claude Code prompts on each by default and create_landing_page's Puck schema is verbose JSON the operator should NOT read. DO TWO THINGS to avoid spamming: (1) RECOMMEND THE OPERATOR pick option 2 ('Yes, and do not ask again for seldonframe – <tool>') the FIRST time create_landing_page / persist_block / build_website_chatbot fire — Claude Code caches per-tool autoapprove for the project, the rest of workspace creation runs without interrupting them. Mention this proactively before the flow starts. (2) BUNDLE TOOL CALLS in parallel via Promise.all — never call get_block_skill + persist_block sequentially for 7 blocks; fire them all at once. v1.36+ LANDING-PAGE COMPOSITION FOR LOCAL-SERVICE BUSINESSES: for trades/service businesses (plumbing, HVAC, locksmith, electrician, roofing, towing, dental, salon, mobile mechanic), default to a 10-section composition: navbar → hero (branded gradient empty-state when no photo) → emergencyStrip (sticky brand-colored banner with phone) → trust strip via the Grid block → servicesGrid (per-service cards with price + duration + Book CTA — replaces the SaaS-style pricing block) → benefits (3 differentiators) → process (3-step what-happens-after-booking) → serviceArea (chip cloud of cities/neighborhoods) → testimonials (5+ quotes — placeholder OK pre-launch) → faq → cta → footer. The Pricing block belongs to TIER-based businesses (SaaS, coaches, gyms) NOT per-service businesses — substitute servicesGrid. v1.36.0 added the servicesGrid, emergencyStrip, serviceArea block types — use them when persisting landing pages for trades verticals. The hero block ships a branded-gradient empty state when heroImage is missing; if the operator does not provide a photo, suggest a stock-photo prompt ('your tech truck on a job, sunset shot in Phoenix') so they can drop one in via /landing → Edit later. v1.37.0 GOOGLE MAPS PASTE → WORKSPACE: when the operator pastes a Google Maps business listing (Top Plumbing Experts, ABC Plumbing of San Antonio, etc.), use create_workspace_from_google_paste — NOT create_full_workspace. Same backend pipeline + same finalize_workspace follow-up; the paste-tool's docstring documents the extraction rules (name → bold title, phone → phone-icon row, address → location-pin line, services → categories chip row + 'Services' section deduped, rating + count → '4.7 ★ (950)' element, weekly_hours → 'Monday: 9 AM-5 PM, Tuesday: closed' parsed into canonical {monday:{enabled:true,start:'09:00',end:'17:00'},...} shape). The weekly_hours field flows DIRECTLY into the booking template's metadata.availability, so the operator's actual hours appear on the public /book page on first GET — no separate configure_booking call. 'Open 24 hours' → start:'00:00', end:'23:59'. 'Closed' day → enabled:false. Wrong key shape (e.g. 'mon' instead of 'monday') is silently dropped by the backend and falls back to Mon-Fri 9-5 defaults. NO Google Places API key required — the paste IS the source of truth. v1.36.4 paired fix: the booking page's normalizeAvailability now accepts both 3-letter and full-name day keys, so any legacy rows already in the DB also hydrate correctly. v1.38.3 ADDITIONAL QUALITY BLOCKS: (a) projectGallery — 6-photo masonry of stock photos auto-fetched per service via Unsplash from queries Claude generates inside enhance-blocks; closes the "feels populated" gap that's the single biggest visible difference between a generic SF workspace and a real-business landing page. (b) stickyMobileCTA — fixed bottom-of-screen Call/Book bar, MOBILE ONLY (md:hidden), industry-standard for trades sites with 2-3x mobile booking lift; auto-included whenever a phone is set. (c) testimonial synthesis from Maps paste — when the operator pastes a Google Maps listing that contains review excerpts, Claude Code extracts them VERBATIM into a 'testimonials' field on create_workspace_from_google_paste; backend renders them as-is. NEVER fabricated — if the paste has no review text, the testimonials block is OMITTED from the page entirely (better empty than fake). The testimonials field in the MCP tool input is OPTIONAL — Claude must omit it when the paste doesn't contain real review text. v1.38.0 ATOMIC HORMOZI-QUALITY OUTPUT: every workspace produced by create_full_workspace OR create_workspace_from_google_paste now ships with Hormozi value-equation hero copy + per-business Unsplash photos + scroll-triggered motion baked in — atomically, no follow-up tool calls, no operator action. Pre-1.38.0 the atomic create produced canned 'Welcome to X' copy from personality content templates; only workspaces where Claude Code did the BLOCK-AS-SKILL flow afterward (get_block_skill + persist_block per block) got the rich output. Tirionforge HVAC happened to look great because of that follow-up; atlantic-plumbing didn't get it. v1.38.0 closes the gap by adding Step 12.7 inside the orchestrator: ONE Claude Opus 4.7 call generates hero + servicesGrid + about + benefits + process + faq + cta from src/blocks/*/SKILL.md (the exact same fat skill files Claude Code reads via get_block_skill — single source of truth, no duplication). Output writes to landingPages.sections (LandingPageSection[]), contentHtml/Css get NULLED, route /l/[orgSlug]/[slug] falls through to <PageRenderer> which auto-wraps below-fold sections in <RevealOnScroll>. Hormozi copy + per-business Unsplash + motion all light up at once. EMAIL-FIRST GUARDRAIL UNCHANGED: create_full_workspace + create_workspace_from_google_paste both still RETURN BEFORE THE EMAIL DANCE — operator can't see URLs until they reply with email, finalize_workspace mints the magic admin link + sends the welcome email via Resend. BYOK pass-through: getAIClient checks organizations.integrations.anthropic.apiKey first, falls back to platform ANTHROPIC_API_KEY env. Cost ~$0.10 per workspace, irrelevant since the operator typically supplies their own key. SOFT-FAIL: any error in Step 12.7 leaves the workspace valid (canned-copy Path A intact); never blocks creation. EXPECTED IMPACT: every fresh workspace looks $10k-tier first-shot, no "create workspace then enhance blocks" two-step dance. v1.40.3 IMAGE PIPELINE FOOLPROOFING: removed the deprecated source.unsplash.com keyless fallback from BOTH resolveHeroImageUrlForQuery and resolveGalleryImageUrlsForQueries. Pre-1.40.3 when the official Unsplash API errored or returned no results we fell back to https://source.unsplash.com/{w}x{h}/?{query} — that endpoint is deprecated and now frequently returns broken responses, which were stored verbatim in landingPages.sections and rendered as broken-image icons before the v1.40.2 onError handler eventually flipped state. The HERO Aesthetic Co. test exposed this: hero showed a broken-image icon despite the gallery rendering 4 medspa photos correctly (proving onError wasn't reliably catching deprecated-CDN failures). Fix: never store a known-broken URL. Hero query miss → empty string → branded-gradient empty-state from frame zero (no broken icon ever). Gallery query miss → SKIP that slot → grid auto-reflows to a clean 4-tile composition instead of 6 tiles with 2 broken. Trade-off: workspaces without UNSPLASH_ACCESS_KEY now ship gradient hero + empty gallery (better than broken images). Operators get full control by setting the env var or replacing images post-launch via update_landing_section. ws1-webhook-pricing-fixes branch ships this; redeploy required.`;
+export const FIRST_CALL_BANNER = `🚀 SeldonFrame v1.40.6 is connected. STEP ZERO: for any workspace task call get_workspace_state({workspace_id}) FIRST — returns workspace identity + integrations status + agents with inline health stats + counts + tailored next_steps in ONE round-trip. Replaces 4-6 progressive discovery calls. ANTI-PATTERNS: don't ls/cat/read .env (SF is hosted, not local files); don't check node/npm versions (irrelevant); don't ask 'is Anthropic key configured?' (state response tells you); don't create a duplicate agent (state response shows existing ones — use update_website_chatbot instead of build_website_chatbot when one exists). Token-budget concept removed in v1.27.9 — ignore stale references. CAPABILITY MAP — pick the right primitive BEFORE exploring tools: (a) "build me a website" → WORKSPACE → create_workspace_v2 + block tools. (b) "add a chatbot to my website / landing page" → AGENT (web chat) → build_website_chatbot (v1.28+ skill bundle: configure_llm + create_agent + publish-test in 1 call; auto-detects ANTHROPIC_API_KEY from env). Drop to primitives (configure_llm_provider + create_agent + publish_agent) only for custom flows. CRITICAL ANTI-PATTERN: chat widgets are NOT blocks. Don't search list_blocks for chat — chat agents are a separate primitive (v1.26+). (c) "auto-reply to inbound SMS/email" → CONVERSATION → send_conversation_turn (one-shot Soul-aware reply, not a website widget). (d) "add hero/services/faq/cta section" → BLOCK → get_block_skill + persist_block. (e) "send campaign email/sms" → MESSAGING. (f) CRM ops → list_contacts/create_deal/etc. CHATBOT CANONICAL FLOW (v1.28+ — 1 call instead of 5): build_website_chatbot({workspace_id, name, faq, pricing_facts, greeting}) → wraps configure_llm + create_agent + publish-test in one call, auto-detects ANTHROPIC_API_KEY from env. Then: operator sandbox-tests at /agents/[id]/test → publish_agent({status:"live"}) auto-runs 8-scenario eval gate (≥87.5% pass required). Observability tools after publish: list_agents, tail_agent_conversations, get_agent_conversation, get_agent_metrics, run_agent_evals, replay_conversation. Dashboard surfaces /agents, /agents/[id]/test, /agents/[id]/settings, /agents/[id]/evals, /agents/[id]/conversations let operators iterate without leaving the browser. WORKSPACE FLOW (legacy reference): create_workspace_v2 → IN PARALLEL for all 7 recommended_blocks (hero, services, about, faq, cta, booking, intake): get_block_skill + persist_block → complete_workspace_v2 → finalize_workspace({workspace_id, email}). Run blocks in PARALLEL (Promise.all) — sequential takes 60+ seconds. v1.10+ CUSTOMIZE: regenerate_block, upload_workspace_image (image_url preferred over base64). v1.11+ STRUCTURAL: get_landing_structure, move_section, delete_section. v1.12+ COMPOSITES: add_composite_section / update_composite_section — manifest ANY block from 12 low-level primitives. Skipping finalize_workspace leaves the operator with no admin login. Every URL is real. NEVER create local files. v1.34+ UI POLISH (smart defaults + optional levers): every published page ships with motion baked in (RevealOnScroll on sections, Stagger on grid blocks, HoverLift on CTAs) — no operator action required. For operators who want to tune intensity: apply_motion_preset({preset: "minimal"|"subtle"|"balanced"|"editorial"}). For operators bringing their own design system: apply_design_md({design_md_content}) accepts the Google Labs DESIGN.md format; import_claude_design_handoff({bundle}) accepts Claude Design's handoff bundle. All three tools are OPTIONAL — surface them only when the operator's vibe asks for it ("make it feel premium", "I have a brand kit", "I just exported from Claude Design"). Never push these on a user who just wants a working site. v1.36+ PROMPT-FATIGUE GUIDANCE: workspace creation typically fires 8–18 MCP tool calls (workspace + blocks + agent + booking + intake + landing). Claude Code prompts on each by default and create_landing_page's Puck schema is verbose JSON the operator should NOT read. DO TWO THINGS to avoid spamming: (1) RECOMMEND THE OPERATOR pick option 2 ('Yes, and do not ask again for seldonframe – <tool>') the FIRST time create_landing_page / persist_block / build_website_chatbot fire — Claude Code caches per-tool autoapprove for the project, the rest of workspace creation runs without interrupting them. Mention this proactively before the flow starts. (2) BUNDLE TOOL CALLS in parallel via Promise.all — never call get_block_skill + persist_block sequentially for 7 blocks; fire them all at once. v1.36+ LANDING-PAGE COMPOSITION FOR LOCAL-SERVICE BUSINESSES: for trades/service businesses (plumbing, HVAC, locksmith, electrician, roofing, towing, dental, salon, mobile mechanic), default to a 10-section composition: navbar → hero (branded gradient empty-state when no photo) → emergencyStrip (sticky brand-colored banner with phone) → trust strip via the Grid block → servicesGrid (per-service cards with price + duration + Book CTA — replaces the SaaS-style pricing block) → benefits (3 differentiators) → process (3-step what-happens-after-booking) → serviceArea (chip cloud of cities/neighborhoods) → testimonials (5+ quotes — placeholder OK pre-launch) → faq → cta → footer. The Pricing block belongs to TIER-based businesses (SaaS, coaches, gyms) NOT per-service businesses — substitute servicesGrid. v1.36.0 added the servicesGrid, emergencyStrip, serviceArea block types — use them when persisting landing pages for trades verticals. The hero block ships a branded-gradient empty state when heroImage is missing; if the operator does not provide a photo, suggest a stock-photo prompt ('your tech truck on a job, sunset shot in Phoenix') so they can drop one in via /landing → Edit later. v1.37.0 GOOGLE MAPS PASTE → WORKSPACE: when the operator pastes a Google Maps business listing (Top Plumbing Experts, ABC Plumbing of San Antonio, etc.), use create_workspace_from_google_paste — NOT create_full_workspace. Same backend pipeline + same finalize_workspace follow-up; the paste-tool's docstring documents the extraction rules (name → bold title, phone → phone-icon row, address → location-pin line, services → categories chip row + 'Services' section deduped, rating + count → '4.7 ★ (950)' element, weekly_hours → 'Monday: 9 AM-5 PM, Tuesday: closed' parsed into canonical {monday:{enabled:true,start:'09:00',end:'17:00'},...} shape). The weekly_hours field flows DIRECTLY into the booking template's metadata.availability, so the operator's actual hours appear on the public /book page on first GET — no separate configure_booking call. 'Open 24 hours' → start:'00:00', end:'23:59'. 'Closed' day → enabled:false. Wrong key shape (e.g. 'mon' instead of 'monday') is silently dropped by the backend and falls back to Mon-Fri 9-5 defaults. NO Google Places API key required — the paste IS the source of truth. v1.36.4 paired fix: the booking page's normalizeAvailability now accepts both 3-letter and full-name day keys, so any legacy rows already in the DB also hydrate correctly. v1.38.3 ADDITIONAL QUALITY BLOCKS: (a) projectGallery — 6-photo masonry of stock photos auto-fetched per service via Unsplash from queries Claude generates inside enhance-blocks; closes the "feels populated" gap that's the single biggest visible difference between a generic SF workspace and a real-business landing page. (b) stickyMobileCTA — fixed bottom-of-screen Call/Book bar, MOBILE ONLY (md:hidden), industry-standard for trades sites with 2-3x mobile booking lift; auto-included whenever a phone is set. (c) testimonial synthesis from Maps paste — when the operator pastes a Google Maps listing that contains review excerpts, Claude Code extracts them VERBATIM into a 'testimonials' field on create_workspace_from_google_paste; backend renders them as-is. NEVER fabricated — if the paste has no review text, the testimonials block is OMITTED from the page entirely (better empty than fake). The testimonials field in the MCP tool input is OPTIONAL — Claude must omit it when the paste doesn't contain real review text. v1.38.0 ATOMIC HORMOZI-QUALITY OUTPUT: every workspace produced by create_full_workspace OR create_workspace_from_google_paste now ships with Hormozi value-equation hero copy + per-business Unsplash photos + scroll-triggered motion baked in — atomically, no follow-up tool calls, no operator action. Pre-1.38.0 the atomic create produced canned 'Welcome to X' copy from personality content templates; only workspaces where Claude Code did the BLOCK-AS-SKILL flow afterward (get_block_skill + persist_block per block) got the rich output. Tirionforge HVAC happened to look great because of that follow-up; atlantic-plumbing didn't get it. v1.38.0 closes the gap by adding Step 12.7 inside the orchestrator: ONE Claude Opus 4.7 call generates hero + servicesGrid + about + benefits + process + faq + cta from src/blocks/*/SKILL.md (the exact same fat skill files Claude Code reads via get_block_skill — single source of truth, no duplication). Output writes to landingPages.sections (LandingPageSection[]), contentHtml/Css get NULLED, route /l/[orgSlug]/[slug] falls through to <PageRenderer> which auto-wraps below-fold sections in <RevealOnScroll>. Hormozi copy + per-business Unsplash + motion all light up at once. EMAIL-FIRST GUARDRAIL UNCHANGED: create_full_workspace + create_workspace_from_google_paste both still RETURN BEFORE THE EMAIL DANCE — operator can't see URLs until they reply with email, finalize_workspace mints the magic admin link + sends the welcome email via Resend. BYOK pass-through: getAIClient checks organizations.integrations.anthropic.apiKey first, falls back to platform ANTHROPIC_API_KEY env. Cost ~$0.10 per workspace, irrelevant since the operator typically supplies their own key. SOFT-FAIL: any error in Step 12.7 leaves the workspace valid (canned-copy Path A intact); never blocks creation. EXPECTED IMPACT: every fresh workspace looks $10k-tier first-shot, no "create workspace then enhance blocks" two-step dance. v1.40.3 IMAGE PIPELINE FOOLPROOFING: removed the deprecated source.unsplash.com keyless fallback from BOTH resolveHeroImageUrlForQuery and resolveGalleryImageUrlsForQueries. Pre-1.40.3 when the official Unsplash API errored or returned no results we fell back to https://source.unsplash.com/{w}x{h}/?{query} — that endpoint is deprecated and now frequently returns broken responses, which were stored verbatim in landingPages.sections and rendered as broken-image icons before the v1.40.2 onError handler eventually flipped state. The HERO Aesthetic Co. test exposed this: hero showed a broken-image icon despite the gallery rendering 4 medspa photos correctly (proving onError wasn't reliably catching deprecated-CDN failures). Fix: never store a known-broken URL. Hero query miss → empty string → branded-gradient empty-state from frame zero (no broken icon ever). Gallery query miss → SKIP that slot → grid auto-reflows to a clean 4-tile composition instead of 6 tiles with 2 broken. Trade-off: workspaces without UNSPLASH_ACCESS_KEY now ship gradient hero + empty gallery (better than broken images). Operators get full control by setting the env var or replacing images post-launch via update_landing_section. ws1-webhook-pricing-fixes branch ships this; redeploy required.`;