@seldonframe/mcp 1.0.8 → 1.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@seldonframe/mcp",
-  "version": "1.0.8",
-  "description": "MCP server for SeldonFrame — AI-native Business OS platform. One command creates a real, hosted workspace with a website, booking page, intake form, CRM, and AI agents. v1.0.8: bulletproof finalize_workspace guardrail (create_workspace response now leads with a DO_NOT_DISPLAY warning string and hides URLs under _pending_after_email so models physically can't paste them to the operator without first calling finalize_workspace). New city/state args on create_workspace drive timezone inference (San Diego, CA → America/Los_Angeles instead of UTC). Backend fixes shipped alongside: classifier broadened so 'Heating', 'Cooling', 'AC', 'Furnace' etc. resolve to local_service / HVAC personality (was leaking to coaching → wrong pipeline stages); 'Your Business' nav placeholder eliminated (workspace.name now flows through); booking duration now defaults to 60 min for HVAC/coaching, 30 min for legal/dental, 45 for agency; black-square hero corner artifacts removed; 'Brain v2' / 'Compiling Soul' loading messages reworded for operators.",
+  "version": "1.1.1",
+  "description": "MCP server for SeldonFrame — AI-native Business OS platform. One command creates a real, hosted workspace with a website, booking page, intake form, CRM, and AI agents. v1.1.1: DEPRECATED `create_workspace` tool. Renamed to `_legacy_create_workspace` (sorts last in tool listings) and the handler returns a deprecation error pointing at `create_full_workspace` without doing anything. Closes the old door so Claude Code is forced onto the atomic pipeline introduced in v1.1.0 — every fix shipped since (timezone, pipeline stages, email collection, admin URL withholding) only activates inside the new pipeline. WELCOME_MARKDOWN updated so create_full_workspace is the only workspace-creation path mentioned anywhere.",
   "type": "module",
   "bin": {
     "seldonframe-mcp": "src/index.js"

package/src/tools.js

@@ -40,168 +40,163 @@ function wsOrDefault(workspace_id) {
 
 export const TOOLS = [
   {
-    name: "create_workspace",
-    description:
-      "Create a LIVE, hosted SeldonFrame workspace with a public website, booking page, intake form, CRM, and AI agents — all on a real <slug>.app.seldonframe.com subdomain. Returns live URLs that work in any browser within seconds. " +
-      "THIS IS THE ONLY WAY to create a SeldonFrame workspace. Do NOT create local files (no soul.json, no scaffolded directory), do NOT call loadSoulPackage, do NOT modify the working directory — even if Claude Code is running inside the SeldonFrame source repo. Every workspace is a hosted production deployment. " +
-      "MANDATORY FOLLOW-UP: After this tool returns, you MUST do exactly two things before the conversation ends — " +
-      "(1) ask the user for their email with the verbatim question 'What email should I use for your account? This is where you'll get your login link and any notifications.' and " +
-      "(2) call `finalize_workspace({ email, name? })` with the email they gave you (or call `collect_operator_email` directly if you need finer control). " +
-      "Never end a workspace creation flow without the email step — the welcome email + admin login + lead capture all depend on it. The response payload's `next_step` field tells you exactly what to do next; follow it. " +
-      "The first workspace is free and requires no API key. When the user mentions a phone, email, address, list of services, or testimonials, pass them as structured fields so the landing page renders with their real content immediately. " +
-      "Example: create_workspace({ name: 'Precision Plumbing Co', phone: '(555) 123-4567', business_description: 'Family-owned residential plumbing in Austin.', services: [{ name: 'Drain Cleaning' }, { name: 'Water Heater Repair' }, { name: 'Leak Detection' }] })",
-    inputSchema: obj(
-      {
-        name: str("Human-readable workspace name."),
-        source: str("Optional URL or description to seed the business profile from."),
-        phone: str("Operator's business phone (any format — we render as-is). Renders in nav, hero, and footer when set."),
-        email: str("Optional contact email surfaced in the landing footer."),
-        address: str("Optional business address. Comma-separated street, city, region, postal, country renders as-is."),
-        city: str("Operator's city (e.g. 'San Diego'). Used to set the workspace timezone so the booking page renders the right hours. ALWAYS include when the user mentions a location."),
-        state: str("Operator's US state code or full name (e.g. 'CA' or 'California'), or Canadian province. Used for timezone inference. ALWAYS include when the user mentions a location."),
-        tagline: str("Short hero tagline (one line)."),
-        business_description: str("One paragraph about the business (used for hero subhead + about section). ALWAYS include the industry words verbatim ('residential HVAC', 'family-owned plumbing', 'dental practice') so the right CRM personality + pipeline stages get seeded."),
+    // May 2, 2026 (v1.1.1) — Renamed from `create_workspace` to
+    // `_legacy_create_workspace` to force Claude Code onto the new
+    // atomic `create_full_workspace` path. The leading underscore
+    // sorts this tool toward the bottom of MCP tool listings, and
+    // the "DEPRECATED" prefix in the description makes it obvious
+    // when the model is browsing tools. The handler does NOT call
+    // the API — it returns a redirect error immediately so even if
+    // Claude Code does invoke this, no workspace is created and the
+    // model is told exactly which tool to use instead.
+    name: "_legacy_create_workspace",
+    description:
+      "DEPRECATED — do not use. Use `create_full_workspace` instead for ALL workspace creation. This tool no longer creates anything; calling it returns an error pointing at the replacement. The atomic `create_full_workspace` runs the entire 13-step pipeline server-side in one call (workspace + business profile + CRM + booking + intake + landing page) and the admin URL is structurally created only by `finalize_workspace` — both fixes that the legacy multi-call sequence couldn't reliably deliver.",
+    inputSchema: obj({}),
+    handler: async () => {
+      return {
+        ok: false,
+        error:
+          "This tool is deprecated. Use create_full_workspace for all new workspaces.",
+        redirect_tool: "create_full_workspace",
+        why:
+          "create_full_workspace runs the entire workspace creation pipeline atomically server-side — same input always produces the same output, no retries, no Claude-Code orchestration. The admin dashboard URL is then created only by finalize_workspace, which structurally enforces the email-collection step. The legacy create_workspace path required Claude Code to chain 15-25 tool calls in some order and skipped finalize_workspace in practice.",
+        next_step: {
+          tool_to_call: "create_full_workspace",
+          docs:
+            "Pass: business_name, city, state, phone, services[], business_description (required), and any of: review_count, review_rating, certifications[], trust_signals[], emergency_service, same_day, service_area[].",
+        },
+      };
+    },
+  },
+  {
+    name: "create_full_workspace",
+    description:
+      "PREFERRED for new workspaces. Atomic, server-side workspace creation: takes structured business info and creates everything in ONE call — workspace, business profile, CRM with industry-specific pipeline stages, booking page with availability, intake form, themed landing page, all deployed with live URLs. " +
+      "Use this instead of create_workspace + a long sequence of customization tools. The pipeline runs server-side with a fixed order — same input always produces same output, no retries, no 404s. " +
+      "MANDATORY FOLLOW-UP: After this returns `status: 'ready'`, ask the operator verbatim 'What email should I use for your account? This is where you'll get your login link and notifications.' Then call `finalize_workspace({ workspace_id, email })`. The admin dashboard URL is ONLY created by finalize_workspace — it does not exist in this response (so there's nothing for you to display prematurely). " +
+      "Example: create_full_workspace({ business_name: 'Summit Air Comfort', city: 'Phoenix', state: 'AZ', phone: '(480) 555-2100', services: ['AC repair', 'heating installation', 'duct cleaning'], business_description: 'Residential and commercial HVAC in Phoenix', review_count: 950, review_rating: 4.7, trust_signals: ['licensed', 'bonded', 'insured'], emergency_service: true, same_day: true, service_area: ['Scottsdale', 'Tempe', 'Mesa'] })",
+    inputSchema: obj(
+      {
+        business_name: str("Business display name (e.g. 'Summit Air Comfort')."),
+        city: str("Operator's city. Drives timezone inference."),
+        state: str("US state code or full name (or Canadian province). Drives timezone inference."),
+        phone: str("Business phone, any format. Renders in nav, hero, footer."),
         services: {
           type: "array",
           description:
-            "List of services / products / offerings the business provides. Renders as the services grid on the landing page. Each item: { name, description? }.",
-          items: {
-            type: "object",
-            properties: {
-              name: { type: "string" },
-              description: { type: "string" },
-            },
-            required: ["name"],
-          },
+            "Services / offerings the business provides — each as a plain string. The classifier reads these to pick the right CRM personality (HVAC, legal, dental, coaching, agency, default).",
+          items: { type: "string" },
         },
-        testimonials: {
+        business_description: str(
+          "One paragraph describing the business — drives the hero subhead, about section, and (critically) the personality classifier. Include industry words verbatim ('residential HVAC', 'family-owned plumbing', 'dental practice')."
+        ),
+        review_count: { type: "number", description: "Optional — number of reviews. Surfaces in trust strip + hero proof metric." },
+        review_rating: { type: "number", description: "Optional — average star rating (e.g. 4.7). Surfaces in trust strip." },
+        certifications: {
           type: "array",
-          description:
-            "Optional customer testimonials to seed the landing page's testimonials section. Each item: { quote, name?, role?, company? }.",
-          items: {
-            type: "object",
-            properties: {
-              quote: { type: "string" },
-              name: { type: "string" },
-              role: { type: "string" },
-              company: { type: "string" },
-            },
-            required: ["quote"],
-          },
+          description: "Optional — credentials like ['EPA-certified', 'NATE-certified']. Surfaces in trust strip.",
+          items: { type: "string" },
+        },
+        trust_signals: {
+          type: "array",
+          description: "Optional — short claims like ['licensed', 'bonded', 'insured']. Surfaces in trust strip.",
+          items: { type: "string" },
+        },
+        emergency_service: { type: "boolean", description: "Optional — operator offers 24/7 emergency service. Surfaces in nav + hero." },
+        same_day: { type: "boolean", description: "Optional — same-day service available. Surfaces in trust strip." },
+        service_area: {
+          type: "array",
+          description: "Optional — cities or neighborhoods served (e.g. ['Scottsdale', 'Tempe']).",
+          items: { type: "string" },
         },
+        email: str("Optional contact email surfaced in the landing footer (NOT the operator's account email — that comes via finalize_workspace)."),
+        address: str("Optional business address."),
       },
-      ["name"],
+      ["business_name", "city", "state", "phone", "services", "business_description"]
     ),
     handler: async (args) => {
       const firstEver = isFirstEverCall();
-      const result = await api("POST", "/workspace/create", {
+      const result = await api("POST", "/workspaces/create-full", {
         body: {
-          name: args.name,
-          source: args.source ?? null,
-          phone: args.phone ?? null,
+          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,
-          city: args.city ?? null,
-          state: args.state ?? null,
-          tagline: args.tagline ?? null,
-          business_description: args.business_description ?? null,
-          services: args.services ?? null,
-          testimonials: args.testimonials ?? null,
         },
         allow_anonymous: true,
       });
-      const ws = result.workspace ?? result;
-      const id = ws.id;
-      if (!id) throw new Error("Server did not return a workspace id.");
-      if (result.bearer_token) {
-        rememberWorkspace({ workspace_id: id, bearer_token: result.bearer_token });
-      } else {
-        setDefaultWorkspace(id);
+
+      if (result?.status !== "ready" || !result?.workspace_id) {
+        return result;
+      }
+
+      // Stash the bearer locally so subsequent MCP calls (finalize_workspace
+      // + the customization tools) can authenticate. We strip the bearer
+      // from the visible response — only Claude Code's stash uses it.
+      if (result._bearer_token) {
+        rememberWorkspace({
+          workspace_id: result.workspace_id,
+          bearer_token: result._bearer_token,
+        });
       }
-      // C6: surface the bearer-token admin URL as the most prominent line
-      // in the response. Operators paste it into their browser and land
-      // directly on the dashboard — no signup, no login, no OAuth.
-      const adminUrl = result.admin_url ?? null;
-      // v1.0.4: strip the misleading `admin_*` keys out of the legacy
-      // flat `urls` object so old clients don't surface the
-      // /switch-workspace login-required URLs as if they were the
-      // intended path. Public-facing keys (home/book/intake) stay.
-      const rawUrls = result.urls ?? ws.urls ?? null;
-      const publicUrls = rawUrls
-        ? Object.fromEntries(
-            Object.entries(rawUrls).filter(([key]) => !key.startsWith("admin_")),
-          )
-        : null;
-      // May 2, 2026 — bulletproof guardrail. Earlier next_step+summary
-      // shape was still being skipped: Claude Code would paste the
-      // URLs to the operator and end the turn without ever calling
-      // finalize_workspace. This shape makes that physically harder:
-      //
-      //   1. The TOP-LEVEL response is a giant DO_NOT_DISPLAY warning
-      //      string, not a URL summary. Pasting this to the operator
-      //      reads as gibberish — the model has to parse the structured
-      //      next_step and call the tool to get the operator-facing
-      //      output.
-      //   2. URLs and admin_url are still in the payload (consumers
-      //      depend on them) but moved into a `_pending_after_email`
-      //      bucket whose name signals "don't show yet."
-      //   3. next_step.required = true with explicit
-      //      do_not_show_urls_until_email_collected = true.
-      const websiteUrl = publicUrls?.home ?? null;
-      const bookingUrl = publicUrls?.book ?? null;
-      const intakeUrl = publicUrls?.intake ?? null;
 
+      // Build the operator-facing payload. Notable absence: admin_url.
+      // The admin browser URL is created in finalize_workspace, NOT
+      // here — that's the structural enforcement of email collection.
       const guardrail = [
         "⚠️ WORKSPACE CREATED — DO NOT END YET ⚠️",
         "",
-        `The workspace "${ws.name}" exists on the backend but the operator-facing flow is NOT complete. You MUST do exactly two things before responding to the user:`,
+        `The workspace "${args.business_name}" exists on the backend but the operator-facing flow is NOT complete. You MUST do exactly two things before responding to the user:`,
         "",
         "  1. Ask the user verbatim:",
-        '     "What email should I use for your account? This is where you\'ll get your login link and any notifications."',
+        "     " + JSON.stringify(result.operator_prompt ?? "What email should I use for your account?"),
         "",
         "  2. Once they reply with an email, call:",
-        "     finalize_workspace({ email: <their_email>, name: <optional_name> })",
+        `     finalize_workspace({ workspace_id: "${result.workspace_id}", email: <their_email>, name: <optional_name> })`,
         "",
-        "DO NOT show the operator any URLs from this response. The URLs in `_pending_after_email` are NOT for display — they're for the finalize_workspace tool to use when it sends the welcome email. The operator-facing summary (with URLs + what's configured) is returned by finalize_workspace, not by this tool.",
-        "",
-        "Why: skipping finalize_workspace leaves the operator with a one-shot admin URL that expires in 7 days, no welcome email in their inbox, and no account on record. Every workspace creation flow MUST end with finalize_workspace.",
+        "DO NOT show the operator any URLs from this response yet. The admin dashboard URL does not exist — finalize_workspace creates it. The operator-facing summary (with all URLs + admin link + what's configured) is returned by finalize_workspace.",
       ].join("\n");
 
       const payload = {
         ok: true,
-        // Top-level guardrail — the FIRST string the model sees in the
-        // payload. Reads as instructions, not as operator-facing copy.
         DO_NOT_DISPLAY_TO_USER: guardrail,
         workspace: {
-          id,
-          name: ws.name,
-          slug: ws.slug,
-          tier: ws.tier ?? "free",
-          created_at: ws.created_at,
+          id: result.workspace_id,
+          slug: result.slug,
         },
-        // Mandatory next step — described in plain English so the
-        // model has no excuse to skip it.
+        configured: result.configured,
         next_step: {
           required: true,
           do_not_show_urls_until_email_collected: true,
-          ask_user_verbatim:
-            "What email should I use for your account? This is where you'll get your login link and any notifications.",
+          ask_user_verbatim: result.operator_prompt,
           tool_to_call: "finalize_workspace",
-          tool_args_template: { email: "<operator_email>", name: "<optional>" },
+          tool_args_template: {
+            workspace_id: result.workspace_id,
+            email: "<operator_email>",
+            name: "<optional>",
+          },
           why_required:
-            "finalize_workspace is what sends the welcome email (Resend), creates the operator's account so the admin login keeps working past the 7-day token, captures them as a lead in our CRM, and returns the formatted operator-facing summary (URLs + what's configured) for you to paraphrase.",
+            "finalize_workspace creates the admin dashboard URL (it does not exist yet), sends the welcome email, captures the operator as a lead, and returns the formatted operator-facing summary. Skipping it leaves the operator with no admin access at all.",
           consequence_of_skipping:
-            "Operator gets a one-shot admin URL with no recovery path, no welcome email, no account on record, no follow-up channel. This IS a broken flow.",
+            "The admin dashboard URL is structurally not in this response. Skipping finalize_workspace means the operator can't get into their workspace. This IS a broken flow.",
         },
-        // URLs are in the payload (downstream consumers may rely on
-        // them) but in a bucket whose name signals "do not display."
+        // Internal-only — public URLs only. No admin URL anywhere.
         _pending_after_email: {
-          website_url: websiteUrl,
-          booking_url: bookingUrl,
-          intake_url: intakeUrl,
-          admin_url: adminUrl,
-          admin_url_expires_at: result.bearer_token_expires_at ?? null,
-          public_urls: result.public_urls ?? publicUrls,
+          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;

package/src/welcome.js

@@ -3,8 +3,12 @@
 // rule and example here is operator-facing copy — no internal slugs,
 // no architecture lecture, no "Soul" / "Cal.diy" / "Formbricks" /
 // "Brain v2" jargon.
+//
+// v1.1.1 — every reference to the deprecated `create_workspace` tool
+// stripped. `create_full_workspace` is the only workspace-creation
+// path mentioned anywhere in this briefing.
 
-export const VERSION = "1.0.8";
+export const VERSION = "1.1.1";
 
 export const WELCOME_MARKDOWN = `# SeldonFrame — create a real Business OS in one conversation
 
@@ -17,8 +21,8 @@ CRM, and AI agents — all on a real subdomain.
 
 ## NEVER CREATE LOCAL FILES
 
-SeldonFrame workspaces are created via the \`create_workspace\` MCP
-tool. They are NOT created by writing files on disk. Specifically:
+SeldonFrame workspaces are created via the \`create_full_workspace\`
+MCP tool. They are NOT created by writing files on disk. Specifically:
 
 - Do NOT create a \`soul.json\` file or any other local file.
 - Do NOT call \`loadSoulPackage\` or any local function.
@@ -27,7 +31,7 @@ tool. They are NOT created by writing files on disk. Specifically:
 
 If you are running inside a SeldonFrame source-code repository and
 the user asks for a workspace, IGNORE the local code — call the
-\`create_workspace\` MCP tool. The tool returns live URLs on
+\`create_full_workspace\` MCP tool. The tool returns live URLs on
 \`<slug>.app.seldonframe.com\` that work in any browser within
 seconds. There is no local-file path. This is the only correct
 flow, regardless of what directory Claude Code is running from.
@@ -38,41 +42,46 @@ flow, regardless of what directory Claude Code is running from.
 
 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 a one-shot URL with no recovery path, no
-welcome email, and no follow-up channel. Always finish with step 4.
+— the operator gets no welcome email, no admin login, and no
+follow-up channel. Always finish with step 4.
 
 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:
    - Business name
    - Industry (HVAC, plumbing, dental, legal, coaching, real-estate, agency, …)
+   - City + state (US state code or full name; Canadian province also OK)
    - Phone number (for local services — for SaaS skip)
    - Top 3-5 services / products
    - Brief description (1 sentence)
 
-2. **Create the workspace.** Call \`create_workspace\` with the
-   structured fields. ALWAYS include city + state when the user
-   mentions a location (drives timezone), and ALWAYS include the
-   industry words verbatim in business_description (drives CRM
-   personality + pipeline stages):
+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.
    \`\`\`
-   create_workspace({
-     name: "Pacific Coast Heating & Air",
-     phone: "(555) 123-4567",
+   create_full_workspace({
+     business_name: "Pacific Coast Heating & Air",
      city: "San Diego",
      state: "CA",
-     business_description: "Family-owned residential HVAC contractor — heating, cooling, AC repair.",
-     services: [
-       { name: "AC Repair" },
-       { name: "Heating Installation" },
-       { name: "Indoor Air Quality" }
-     ]
+     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"],
+     emergency_service: true,
+     same_day: true,
+     service_area: ["San Diego", "Chula Vista", "Oceanside"]
    })
    \`\`\`
-   The response is a guardrail payload — its top field is a giant
-   "DO NOT DISPLAY" warning string and the URLs live under
-   \`_pending_after_email\`. Do NOT present anything from this
-   response to the operator. Move directly to step 3.
+   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.
 
 3. **Ask the operator for their email — VERBATIM.** Use exactly this
    wording so the operator understands why it's needed:
@@ -82,21 +91,28 @@ welcome email, and no 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({ email })\`.** This is the
-   one tool call that closes the loop:
+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({ email: "max@precisionplumbing.com", name: "Max" })
+   finalize_workspace({
+     workspace_id: "<from-create_full_workspace-response>",
+     email: "max@pacificcoasthvac.com",
+     name: "Max"
+   })
    \`\`\`
-   It sends the welcome email (with all the URLs), 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).
+   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.
+   satisfies step 4; skipping both does not — and the operator
+   is left with NO admin access at all.
 
 After step 4 the operator can customize their workspace through
 further natural-language requests ("change the headline to …",
@@ -107,14 +123,19 @@ further natural-language requests ("change the headline to …",
 
 ## What the tools do (operator language only)
 
-- **\`create_workspace\`** — creates the live business OS (website,
-  booking, intake form, CRM, AI agents). Always the first call.
-- **\`finalize_workspace\`** — MANDATORY closing call. Bundles email
-  collection (welcome email + lead capture) and returns the
-  formatted final summary Claude Code paraphrases verbatim to the
-  operator. Always the last call of every workspace creation flow.
-- **\`collect_operator_email\`** — same effect as finalize_workspace
-  but without the formatted summary. Use either; never skip both.
+- **\`create_full_workspace\`** — the ONE workspace-creation tool.
+  Atomic, server-side, deterministic. Always the first call for
+  new workspaces.
+- **\`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
+  returns the formatted final summary Claude Code paraphrases
+  verbatim to the operator. Always the last call of every
+  workspace creation flow.
+- **\`collect_operator_email\`** — narrower variant of
+  finalize_workspace that only sends the welcome email + captures
+  the lead. Doesn't return the formatted summary. Use either;
+  never skip both.
 - **\`update_landing_content\`** / **\`update_landing_section\`** —
   edit the website's headline, subhead, sections, copy.
 - **\`update_theme\`** — change colors, fonts, dark/light mode.
@@ -152,4 +173,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_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({ email }) so the operator gets their welcome email + admin login — skipping it is a broken flow.`;
+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.`;