@seldonframe/mcp 1.3.5 → 1.4.0

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.3.5",
+  "version": "1.4.0",
+  "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.4.0: ARCHITECTURAL SHIFT — block-as-skill primitives + MCP-native workspace creation (the Karpathy-inflected 'thin harness, fat skills' move). Pre-1.4 the SF backend generated all landing-page copy server-side from a hardcoded personality system + JSON templates + 6+ deterministic transforms. Every new niche surfaced a fresh layer-mismatch bug (10 v1.3.x releases shipped fixes for the same bug class). v1.4.0 inverts the architecture for the highest-stakes copy surfaces — hero, services, faq — by moving block GENERATION out of the SF backend and into the operator's IDE agent (Claude Code, Cursor, Windsurf, etc.). Each block now lives as a single-source-of-truth folder under packages/crm/src/blocks/<name>/SKILL.md containing the prop schema (YAML frontmatter) + generation prompt + voice rules + worked examples + validator definitions (markdown body). Five new MCP tools enable the v2 flow: (1) create_workspace_v2 — bootstraps the workspace via the v1 orchestrator, returns recommended_blocks + workspace context for the IDE agent's LLM; (2) list_blocks — discovers v2 page primitives; (3) get_block_skill — returns raw SKILL.md the IDE agent reads; (4) persist_block — validates props against the block's Zod schema + deterministic copy-quality validators (headline_quantified, distinct_icons, no_coaching_leak, no_throat_clearing, etc.), maps props onto the existing LandingSection shape, re-renders the full landing via the v1 renderer, persists block_instances row + landing_pages update; (5) complete_workspace_v2 — reports which blocks landed vs. fell back to v1 defaults. Forever-frozen edits live in block_instances.customizations (jsonb append-only) so operator edits via 'customize' calls survive workspace re-rolls. v1 (create_full_workspace) still owns booking, intake, about, theme, pipeline, CRM — and remains the safe fallback for any caller that doesn't know about v2 yet. ⚠️ BACKEND REDEPLOY REQUIRED + apply migration 0036_block_instances.sql in production. v1.5 will land the SKILL.md → __generated__/ codegen so the prop schema lives in exactly one place.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.3.5: Three Karpathy-flavored root-cause fixes shipped in one cycle, all motivated by what the Iron & Oak Barbershop test surfaced. (FIX D — booking + intake 400 on subdomains) The C4 booking client and C5 intake client both extracted orgSlug from window.location.pathname, expecting /book/<slug>/<bookingSlug> or /forms/<slug>/<formSlug>. On a workspace subdomain (<slug>.app.seldonframe.com) the proxy rewrites the path server-side but the BROWSER URL stays at /book or /intake — clients saw no slug, posted orgSlug='', and every visitor's submission rejected with missing_required_field 400. Server-side defense in depth: new resolveWorkspaceSlugFromHostHeader helper in lib/workspace/host-to-slug.ts mirrors proxy.ts logic; both public POST routes now derive orgSlug from the Host header when the body value is missing. Client-side defense in depth: both renderers fall back to `window.location.hostname.split('.')[0]` when pathParts[1] is empty. Plus public_intake_succeeded/_rejected logs (parity with v1.3.3 booking observability) so the intake funnel is visible end-to-end. New slug_source tag on success logs lets us measure how often the host fallback rescues a request. (FIX E — pipeline validator's HTML-entity blind spot) The 'BUSINESS NAME NOT IN HTML' check in pipeline-validator.ts did a literal substring search on the rendered HTML. Business names with HTML-special chars ('Iron & Oak Barbershop', \"Joe's Plumbing\", '<3 Salon') get entity-encoded by the renderer ('Iron &amp; Oak Barbershop'), so the literal check missed them and emitted false-positive blocking errors even though the name WAS rendered correctly. New htmlContainsText helper tries the literal needle, then its HTML-escaped form, then the &apos; variant — same logic for the first-offering fallback. Validator was wrong, not the rendering pipeline. (FIX F — model upgrade) Default ANTHROPIC_MODEL is now claude-opus-4-7 (was claude-sonnet-4-20250514). Personality generation is a once-per-niche cost — the cache amortizes Opus across every future workspace in that vertical, so the per-workspace blended cost stays near-zero while cold-call quality improves meaningfully on long-tail niches (pet grooming, accounting, voiceover, etc.). Three-tier fallback chain: Opus 4.7 (primary) → Sonnet 4.5 / claude-sonnet-4-5-20250929 (secondary) → Haiku 3.5 (tertiary). Each tier overridable via ANTHROPIC_MODEL / ANTHROPIC_MODEL_FALLBACK / ANTHROPIC_MODEL_TERTIARY env vars; chain walks down on any 404 so a single model retirement never takes the system offline. ⚠️ BACKEND REDEPLOY REQUIRED. No env vars to set on Vercel — Opus is the new default; if cost is a concern set ANTHROPIC_MODEL=claude-sonnet-4-5-20250929 to revert.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.3.4: ROOT-CAUSE the last 3 'wrong default everywhere' bugs from the Iron & Oak Barbershop test by extending CRMPersonality with two new LLM-populated fields + closing the booking → CRM kanban loop. (FIX A — booking metadata personalization) Pre-1.3.4 the booking calendar showed 'Free consultation / 30-minute conversation' for ANY niche not in personalityBookingDefaults (only 7 hardcoded verticals — barbershop, photography, accounting, tutoring, etc. all leaked the general.json template default). New optional CRMPersonality.booking field { title, description, duration_minutes, location_kind } populated by the LLM via the personality generator's prompt. createAnonymousWorkspace applies it as the highest-priority source (LLM > personalityBookingDefaults > JSON template). location_kind enum mirrors the blueprint's eventType.location.kind exactly (on-site-business / on-site-customer / phone / video / hybrid) so there's zero translation. (FIX B — hero image relevance) Pre-1.3.4 every workspace whose vertical wasn't in the curated IMAGES map fell back to GENERAL_IMAGES (hand-picked CONTRACTOR photos — bizarre for nail salons, tutoring, barbershops). New optional CRMPersonality.images.hero_query field — free-text Unsplash search query the LLM picks per-niche ('barbershop interior', 'math tutoring student', 'nail salon manicure'). New resolveHeroImageUrlForQuery function tries the official Unsplash API first when UNSPLASH_ACCESS_KEY is set, then falls back to source.unsplash.com keyless redirect. applyPersonalityImagesToSchema is now async and prefers LLM > curated > skip. (FIX C — bookings appear in CRM kanban) Pre-1.3.4 submitPublicBookingAction inserted into bookings + activities + contacts but NEVER into deals — so the visitor's confirmed appointment never appeared in /deals where operators actually triage their pipeline. v1.3.4 calls ensureDefaultPipelineForOrg (lazy-seeds when missing) and INSERTs a deal at the first stage on every successful free booking, with customFields.bookingId for reconciliation against future booking events. Wrapped in try/catch + structured public_booking_deal_created/_failed events — a deal-insert failure does NOT roll back the booking. (VALIDATOR) +3 new checks: hero_image_loadable (asserts the rendered URL belongs to a known Unsplash host pattern + has sizing params), booking_title_personalized (asserts the booking title doesn't contain 'Free consultation' / '30-minute conversation' AND uses the personality's title if declared), booking_to_deal_pipeline_ready (asserts the org's first pipeline stage has a non-empty name so deal-insertion lands in a renderable kanban column). ⚠️ BACKEND REDEPLOY REQUIRED. Optional: set UNSPLASH_ACCESS_KEY on Vercel to use the official API for hero images instead of the keyless source.unsplash.com redirect.",
   "description": "MCP server for SeldonFrame — AI-native Business OS platform. v1.3.3: ROOT CAUSE for the recurring 'wrong personality everywhere except landing' bug pattern + booking observability + per-service enrichment. (FIX 1) The booking POST /api/v1/public/bookings was returning 400 with literally NO LOGS ('No logs found for this request' in Vercel UI). Every reject path now emits a single-line structured JSON event (event: public_booking_rejected, reason: <stable_id>, ...context) so we can finally see WHICH validation is rejecting bookings. submitPublicBookingAction got the same treatment: every throw now logs reason + booking context (org_slug, weekday_in_workspace_tz, slot_local_hhmm, day_start, day_end, ...). The next time someone hits 'Couldn't book that time', the Vercel log will name the exact cause. (FIX 2 — REAL ROOT CAUSE) The LLM-generated CRMPersonality from create-full.ts was being THROWN AWAY by createAnonymousWorkspace — which called selectCRMPersonality (keyword-based) internally, ignoring the resolved personality. So booking template + intake form + landing seed all used the keyword-fallback personality (e.g. 'general' for nail salons → 'Get in Touch' intake title, 'New Lead → Quoted → ...' pipeline) while only the post-seed defensive override updated settings.crmPersonality with the LLM personality. Result: rendered intake HTML never had the personality title; that's why intake_title_rendered_html: FAIL kept appearing. Fix: createAnonymousWorkspace now accepts an opts.personality parameter; create-full.ts passes the LLM-resolved personality through. Booking template + intake form + landing seed all use the LLM personality from the start. (FIX 3a) Light mode is now the default fallback when personality.theme.mode is unset — premium verticals must opt in to dark via theme.mode='dark'. Previously the fallback used the BusinessType heuristic which routed saas/agency to cinematic (dark) by default. (FIX 3d/e) New optional services_enrichment field on CRMPersonality: array with one entry per operator service { service_name, description, icon }. The LLM is prompted to populate it with customer-facing descriptions + distinct icons per service from a known allowlist. Pipeline merges descriptions onto soul.offerings (so service cards show body copy) and overrides applyServiceIconsFromPersonality (so each card has a distinct LLM-picked icon instead of the keyword classifier's homogenous defaults). ⚠️ BACKEND REDEPLOY REQUIRED. Run a niche test post-deploy: every personality_resolved log line now also tells you whether bookings persist (public_booking_succeeded) or why they reject (public_booking_rejected with reason).",

package/src/tools.js

@@ -2433,6 +2433,233 @@ export const TOOLS = [
       return result;
     },
   },
+
+  // ─── v1.4.0 — v2 (MCP-native) workspace creation ────────────────────────
+  //
+  // The v2 flow shifts block GENERATION out of the SF backend and into the
+  // IDE agent's LLM context. Operator's IDE agent (Claude Code, Cursor,
+  // Windsurf, etc.) reads each block's SKILL.md, generates props with its
+  // own LLM, and posts the props back to SF. SF persists + renders.
+  //
+  // PREFERRED for new workspace creation as of v1.4. The v1
+  // create_full_workspace tool above still works (and v1 still owns
+  // booking, intake, about, theme, pipeline) — v2 only owns hero, services,
+  // and faq for now (the highest-stakes copy surfaces, where the v1 layer-
+  // mismatch bug class hurt most).
+
+  {
+    name: "create_workspace_v2",
+    description:
+      "PREFERRED for new workspaces (v1.4+). MCP-native workspace creation: bootstraps the workspace via the v1 orchestrator (CRM, booking, intake, theme, pipeline) AND returns a list of v2 page blocks the IDE agent will now generate using its own LLM. " +
+      "Flow: 1) call this tool with the operator's business info; 2) for each block in `v2.recommended_blocks`, call get_block_skill(name) and use your LLM to generate props matching the SKILL.md prompt + schema; 3) call persist_block({ workspace_id, block_name, generation_prompt, props }) for each; 4) call complete_workspace_v2({ workspace_id }). " +
+      "MANDATORY FOLLOW-UP: After this returns `status: 'ready'` AND after all blocks land via persist_block + complete_workspace_v2, ask the operator verbatim 'What email should I use for your account?' Then call finalize_workspace({ workspace_id, email }). The admin dashboard URL is created by finalize_workspace, not here. " +
+      "Why v2: v1 generated all copy server-side from a hardcoded personality system, which produced layer-mismatch bugs every time a new niche was tested. v2 puts the LLM in your context (the IDE agent), reads from one SKILL.md per block, and the generated copy is naturally niche-aware. The operator can later say 'change the hero' and you customize it via persist_block with a customization payload.",
+    inputSchema: obj(
+      {
+        business_name: str("Business display name."),
+        city: str("Operator's city. Drives timezone inference."),
+        state: str("US state code or full name (or Canadian province)."),
+        phone: str("Business phone, any format."),
+        services: {
+          type: "array",
+          description: "Services / offerings the business provides — each as a plain string.",
+          items: { type: "string" },
+        },
+        business_description: str(
+          "One paragraph describing the business — drives the personality classifier and feeds into block prompts."
+        ),
+        review_count: { type: "number", description: "Optional — number of reviews." },
+        review_rating: { type: "number", description: "Optional — average star rating." },
+        certifications: { type: "array", items: { type: "string" } },
+        trust_signals: { type: "array", items: { type: "string" } },
+        emergency_service: { type: "boolean" },
+        same_day: { type: "boolean" },
+        service_area: { type: "array", items: { type: "string" } },
+        email: str("Optional contact email surfaced in the landing footer (NOT the operator's account email)."),
+        address: str("Optional business address."),
+      },
+      ["business_name", "city", "state", "phone", "services", "business_description"],
+    ),
+    handler: async (args) => {
+      const firstEver = isFirstEverCall();
+      const result = await api("POST", "/workspace/v2/create", {
+        body: {
+          business_name: args.business_name,
+          city: args.city,
+          state: args.state,
+          phone: args.phone,
+          services: args.services,
+          business_description: args.business_description,
+          review_count: args.review_count ?? null,
+          review_rating: args.review_rating ?? null,
+          certifications: args.certifications ?? null,
+          trust_signals: args.trust_signals ?? null,
+          emergency_service: args.emergency_service ?? null,
+          same_day: args.same_day ?? null,
+          service_area: args.service_area ?? null,
+          email: args.email ?? null,
+          address: args.address ?? null,
+        },
+        allow_anonymous: true,
+      });
+
+      if (result?.status !== "ready" || !result?.workspace_id) {
+        return result;
+      }
+
+      // Stash the bearer locally so subsequent persist_block + finalize calls
+      // can authenticate. Stripped from the visible response.
+      if (result._bearer_token) {
+        rememberWorkspace({
+          workspace_id: result.workspace_id,
+          bearer_token: result._bearer_token,
+        });
+      }
+
+      // Operator-facing payload + structural enforcement that the IDE agent
+      // does the block generation step before showing URLs to the user.
+      const guardrail = [
+        "⚠️ V2 WORKSPACE BOOTSTRAPPED — DO NOT END YET ⚠️",
+        "",
+        `The workspace "${args.business_name}" exists on the backend with default copy from the v1 personality system. To complete the v2 flow you MUST:`,
+        "",
+        "  1. For each block in v2.recommended_blocks:",
+        "     a. call get_block_skill({ block_name }) to load the SKILL.md prompt + prop schema",
+        "     b. use your LLM to generate props matching that schema, using v2.context as the input",
+        "     c. call persist_block({ workspace_id, block_name, generation_prompt, props })",
+        "  2. call complete_workspace_v2({ workspace_id }) to validate the final state",
+        "  3. ask the operator: " + JSON.stringify(result.operator_prompt ?? "What email should I use for your account?"),
+        "  4. call finalize_workspace({ workspace_id, email }) to mint the admin URL",
+        "",
+        "DO NOT show the operator any URLs from this response yet — the page is rendering with v1 default copy until step 1 lands. Step 1 produces the niche-aware copy the operator is going to actually see.",
+      ].join("\n");
+
+      const payload = {
+        ok: true,
+        DO_NOT_DISPLAY_TO_USER: guardrail,
+        workspace: { id: result.workspace_id, slug: result.slug },
+        configured: result.configured,
+        v2: result.v2,
+        next_step: {
+          required: true,
+          do_not_show_urls_until_blocks_persisted_and_email_collected: true,
+          tool_to_call_first: "get_block_skill",
+          then_for_each_block: "persist_block",
+          then: "complete_workspace_v2",
+          finally: "finalize_workspace",
+          ask_user_verbatim: result.operator_prompt,
+        },
+        _pending_after_completion: {
+          website_url: result.public_urls?.home ?? null,
+          booking_url: result.public_urls?.book ?? null,
+          intake_url: result.public_urls?.intake ?? null,
+        },
+      };
+      return firstEver ? withFirstCallBanner(payload) : payload;
+    },
+  },
+
+  {
+    name: "list_blocks",
+    description:
+      "List all v2 page-block primitives available in this SF backend. Returns each block's name, version, section type, one-line description, and the URL where its full SKILL.md (the generation prompt + prop schema) lives. Use this when you need to discover what blocks exist; for actual block content use get_block_skill.",
+    inputSchema: obj({}),
+    handler: async () => {
+      const result = await api("GET", "/public/blocks/list", { allow_anonymous: true });
+      return result;
+    },
+  },
+
+  {
+    name: "get_block_skill",
+    description:
+      "Fetch the SKILL.md (the full generation prompt + prop schema + voice rules + worked examples + validator definitions) for one v2 page block. Returns raw markdown text. Read it carefully BEFORE generating props — the prop schema in the YAML frontmatter is enforced by the persist_block endpoint, and the validators run on every save. Generation that ignores the SKILL.md will fail validation and the operator will see worse output.",
+    inputSchema: obj(
+      { block_name: str("Block name. Use list_blocks to discover. As of v1.4: hero, services, faq.") },
+      ["block_name"],
+    ),
+    handler: async (args) => {
+      const path = `/public/blocks/${encodeURIComponent(args.block_name)}/skill`;
+      // Custom fetch — the SKILL.md endpoint returns text/markdown, not JSON.
+      const res = await fetch(`${API_INFO.base}${path}`);
+      if (!res.ok) {
+        const errBody = await res.text();
+        throw new Error(`get_block_skill ${res.status}: ${errBody}`);
+      }
+      const skill_md = await res.text();
+      return {
+        block_name: args.block_name,
+        skill_md,
+        usage:
+          "The frontmatter (between the --- markers) defines the prop schema and validators. The body is the generation prompt — read it as if it were addressed to you. Generate JSON matching the prop schema, then call persist_block.",
+      };
+    },
+  },
+
+  {
+    name: "persist_block",
+    description:
+      "Persist a v2 block instance. Call this after you've read the block's SKILL.md and generated props matching its schema. The server validates props (Zod schema + deterministic copy-quality validators), renders the block via the existing renderer, replaces the matching section in the workspace's landing page, and returns the public URL where the change is now visible. " +
+      "For initial generation, omit `customization`. For operator-driven edits ('make the hero warmer', 'add a card about kids cuts'), pass `customization: { prompt }` — the operator's prompt is appended to the row's customization history (forever-frozen rule), and the new props replace the previous render. " +
+      "Returns `validation_errors` on failure — if you see them, regenerate the props with the rules from SKILL.md applied more carefully and retry. Don't show validation errors to the operator; they're for you.",
+    inputSchema: obj(
+      {
+        workspace_id: str("Workspace id from create_workspace_v2."),
+        block_name: str("Block name (must match a get_block_skill name): hero, services, or faq."),
+        generation_prompt: str(
+          "The full prompt your LLM consumed to produce these props. Stored as the source of truth for re-renders. Include the workspace context (business name, services, etc.) — not just the SKILL.md body."
+        ),
+        props: {
+          type: "object",
+          description:
+            "Block props matching the prop schema in the block's SKILL.md frontmatter. Validated server-side; mismatches return 422 with structured validation_errors.",
+          additionalProperties: true,
+        },
+        customization: {
+          type: "object",
+          description:
+            "Optional operator-customization layer. When set, append-only override of the initial generation. Use this when the operator says 'change X about my hero' rather than 'rewrite my hero'.",
+          properties: {
+            prompt: str("The operator's natural-language customization request."),
+            source: str("Optional source identifier (e.g. 'claude-code/desktop-7af3') for audit logs."),
+          },
+        },
+      },
+      ["workspace_id", "block_name", "generation_prompt", "props"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/workspace/v2/blocks", {
+        body: {
+          workspace_id: ws,
+          block_name: args.block_name,
+          generation_prompt: args.generation_prompt,
+          props: args.props,
+          customization: args.customization ?? null,
+        },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
+
+  {
+    name: "complete_workspace_v2",
+    description:
+      "Mark the v2 flow finished for a workspace. Returns which blocks landed vs. were skipped (skipped ones still render via the v1 default pipeline), plus the next steps. Call after every recommended_block has been persisted via persist_block. The operator-facing summary (admin URL, etc.) still requires finalize_workspace afterward.",
+    inputSchema: obj(
+      { workspace_id: str("Workspace id from create_workspace_v2.") },
+      ["workspace_id"],
+    ),
+    handler: async (args) => {
+      const ws = args.workspace_id;
+      const result = await api("POST", "/workspace/v2/complete", {
+        body: { workspace_id: ws },
+        workspace_id: ws,
+      });
+      return result;
+    },
+  },
 ];
 
 export const TOOL_MAP = Object.fromEntries(TOOLS.map((t) => [t.name, t]));

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.3.3";
+export const VERSION = "1.4.0";
 
 export const WELCOME_MARKDOWN = `# SeldonFrame — create a real Business OS in one conversation
 
@@ -38,16 +38,20 @@ flow, regardless of what directory Claude Code is running from.
 
 ---
 
-## The full happy path — 4 steps, NO EXCEPTIONS
+## The full happy path — 6 steps (v2 — PREFERRED)
 
-EVERY workspace creation flow has exactly these 4 steps, in order.
-Step 4 is MANDATORY. A flow that ends after step 2 or 3 is broken
-— the operator gets no welcome email, no admin login, and no
-follow-up channel. Always finish with step 4.
+As of v1.4.0 the workspace-creation flow is MCP-native: YOU (the IDE
+agent) generate the high-stakes copy blocks (hero, services, faq) using
+your own LLM, reading from a SKILL.md the SF backend serves. v1's
+server-side personality system still runs underneath for everything
+else (CRM, booking, intake, theme, pipeline) — v2 only owns the copy
+surfaces where v1's layer-mismatch bugs hurt most.
 
-1. **Ask for the business details.** When the user says "create a
-   workspace," gather these conversationally — one or two
-   questions per turn, not all at once:
+If you find yourself reaching for \`create_full_workspace\` instead of
+\`create_workspace_v2\`, stop — that's the legacy path. It still works
+but the output quality is worse on niches outside SF's curated set.
+
+1. **Ask for the business details** (same as before — gather conversationally):
    - Business name
    - Industry (HVAC, plumbing, dental, legal, coaching, real-estate, agency, …)
    - City + state (US state code or full name; Canadian province also OK)
@@ -55,21 +59,15 @@ follow-up channel. Always finish with step 4.
    - Top 3-5 services / products
    - Brief description (1 sentence)
 
-2. **Create the workspace atomically.** Call \`create_full_workspace\`.
-   One call → the entire workspace deploys server-side: org +
-   business profile + CRM with industry-specific pipeline + booking
-   page with availability + intake form + themed landing page.
-   Same input always produces the same output — no retries, no
-   404s, no Claude-Code orchestration.
+2. **Bootstrap the workspace via v2.** Call \`create_workspace_v2\`:
    \`\`\`
-   create_full_workspace({
+   create_workspace_v2({
      business_name: "Pacific Coast Heating & Air",
      city: "San Diego",
      state: "CA",
      phone: "(555) 123-4567",
      services: ["AC Repair", "Heating Installation", "Indoor Air Quality"],
      business_description: "Family-owned residential HVAC contractor — heating, cooling, AC repair in the San Diego area.",
-     // Optional but recommended — enrich the hero proof metrics:
      review_count: 950,
      review_rating: 4.7,
      trust_signals: ["licensed", "bonded", "insured"],
@@ -78,12 +76,45 @@ follow-up channel. Always finish with step 4.
      service_area: ["San Diego", "Chula Vista", "Oceanside"]
    })
    \`\`\`
-   The response carries a guardrail (\`DO_NOT_DISPLAY_TO_USER\`) and
-   intentionally OMITS the admin dashboard URL — it does not exist
-   yet. Do NOT present anything from this response to the operator.
-   Move directly to step 3.
+   The response carries \`v2.recommended_blocks\` (which blocks YOU now
+   generate) and \`v2.context\` (the input to feed into each block's
+   prompt). Do NOT show URLs to the operator yet — the page is still
+   rendering with v1 default copy.
+
+3. **For each block in \`v2.recommended_blocks\` — generate + persist.**
+   Iterate over them sequentially or in parallel; both work.
+   For each one:
+   \`\`\`
+   // a. Read the SKILL.md
+   const skill = await get_block_skill({ block_name: "hero" });
+   // skill.skill_md is markdown text. Read it carefully — the YAML
+   // frontmatter is the prop schema (enforced server-side); the
+   // body is YOUR generation prompt.
+
+   // b. Generate props with your own LLM. Use v2.context as input.
+   //    Example prompt to yourself: "Following the SKILL.md below,
+   //    produce a JSON object that satisfies its schema for the
+   //    business described in <v2.context>. ..."
+   //    Output: a JSON object matching the schema.
+
+   // c. Persist
+   await persist_block({
+     workspace_id,
+     block_name: "hero",
+     generation_prompt: "<the prompt you used, full text>",
+     props: { headline: "...", subhead: "...", cta_primary: {...}, ... }
+   });
+   \`\`\`
+   If \`persist_block\` returns \`validation_errors\`, regenerate with
+   the SKILL.md rules applied more carefully. Do NOT show validation
+   errors to the operator — they're for you to self-correct.
 
-3. **Ask the operator for their email — VERBATIM.** Use exactly this
+4. **Mark v2 complete.** Call \`complete_workspace_v2({ workspace_id })\`.
+   Returns which blocks landed and any that were skipped. Skipped
+   blocks still render via v1 default copy — the workspace is fully
+   usable either way, but v2 blocks are higher quality.
+
+5. **Ask the operator for their email — VERBATIM.** Use exactly this
    wording so the operator understands why it's needed:
    > "What email should I use for your account? This is where
    > you'll get your login link and any notifications."
@@ -91,28 +122,24 @@ follow-up channel. Always finish with step 4.
    is required to keep their admin login alive past 7 days — then
    ask again. Don't move on without an answer.
 
-4. **MANDATORY: call \`finalize_workspace({ workspace_id, email })\`.**
-   This is the one tool call that closes the loop AND creates the
-   admin dashboard URL (which doesn't exist until this runs):
-   \`\`\`
-   finalize_workspace({
-     workspace_id: "<from-create_full_workspace-response>",
-     email: "max@pacificcoasthvac.com",
-     name: "Max"
-   })
-   \`\`\`
-   It mints the admin auth token, sends the welcome email (with
-   all the URLs and the admin link), captures the operator as a
-   lead in our CRM, and returns a \`summary\` field with the
-   formatted final output. PARAPHRASE that summary verbatim to the
-   operator — that's how they see what was configured (CRM
-   personality, pipeline stages, live URLs, admin link, email
-   confirmation).
-
-   Alternative: call \`collect_operator_email({ email })\` if you
-   want finer control without the formatted summary. Either tool
-   satisfies step 4; skipping both does not — and the operator
-   is left with NO admin access at all.
+6. **MANDATORY: call \`finalize_workspace({ workspace_id, email })\`.**
+   This mints the admin auth token, sends the welcome email (with
+   all the URLs and the admin link), captures the operator as a lead
+   in CRM, and returns a \`summary\` field with the formatted final
+   output. PARAPHRASE that summary verbatim to the operator — that's
+   how they see what was configured.
+
+## v1 fallback (legacy — NOT preferred)
+
+\`create_full_workspace\` still works as the v1 atomic creation path.
+Use it ONLY when:
+- The operator's IDE agent has no LLM (script context, no Anthropic key)
+- A network failure prevents repeated tool calls and you need atomicity
+- You're writing automated tests that don't want to think about block
+  generation
+
+In normal interactive operator-facing flows, prefer v2 every time. The
+v2 quality gradient over v1 is meaningful on long-tail niches.
 
 After step 4 the operator can customize their workspace through
 further natural-language requests ("change the headline to …",
@@ -123,9 +150,18 @@ further natural-language requests ("change the headline to …",
 
 ## What the tools do (operator language only)
 
-- **\`create_full_workspace\`** — the ONE workspace-creation tool.
-  Atomic, server-side, deterministic. Always the first call for
-  new workspaces.
+- **\`create_workspace_v2\`** — PREFERRED workspace-creation tool (v1.4+).
+  MCP-native: bootstraps the workspace + returns the list of blocks YOU
+  generate using your own LLM. The first call for any new workspace.
+- **\`list_blocks\`** — lists v2 page-block primitives available.
+- **\`get_block_skill\`** — fetches one block's SKILL.md (the generation
+  prompt + prop schema you read before generating props).
+- **\`persist_block\`** — saves a block instance you generated. Validates
+  + renders + replaces the matching section in the workspace's landing.
+- **\`complete_workspace_v2\`** — marks the v2 flow finished, reports which
+  blocks landed.
+- **\`create_full_workspace\`** — v1 atomic creation (legacy). Server-side,
+  deterministic. Use only when v2 is impossible.
 - **\`finalize_workspace\`** — MANDATORY closing call. Mints the
   admin auth token (the admin URL doesn't exist until this runs),
   bundles email collection (welcome email + lead capture), and
@@ -173,4 +209,4 @@ admin dashboard. Pre-fills their email automatically.
 <https://seldonframe.com> · **Discord:** <https://discord.gg/sbVUu976NW>
 `;
 
-export const FIRST_CALL_BANNER = `🚀 SeldonFrame is connected. Ready to create a live business OS — every URL the create_full_workspace tool returns is real and works in any browser within seconds. NEVER create local files; always use the MCP tools. EVERY workspace creation flow must end with finalize_workspace({ workspace_id, email }) so the operator gets their welcome email + admin login — skipping it is a broken flow.`;
+export const FIRST_CALL_BANNER = `🚀 SeldonFrame v1.4 is connected. PREFERRED workspace creation: create_workspace_v2 → for each recommended_block: get_block_skill + persist_block → complete_workspace_v2 → finalize_workspace({ workspace_id, email }). The v2 flow puts YOUR LLM in charge of high-stakes copy (hero, services, faq) using one SKILL.md per block. Every URL is real and works in any browser within seconds. NEVER create local files. Skipping finalize_workspace leaves the operator with no admin login — always close the loop.`;