fix: humanize brand defaults, make brand setup required in agent workflow

- Registration/provision now uses title-cased org name for brand
  ("Will Use Case Selling Posthog" not "will use case selling posthog")
- Brand headline uses "Welcome to {orgName}" not raw slug
- CLAUDE.md: brand creation changed from optional to required step
- MCP tool table marks graspful_create_brand and graspful_import_brand
  as required
- E2E test: new step verifies brand name/headline are not raw slug garbage

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: willwearing

CLAUDE.md

@@ -45,10 +45,10 @@ If MCP is already configured, you have these tools available — no CLI needed:
 | `graspful_validate` | No | Validate YAML against schema |
 | `graspful_review_course` | No | Run 10 quality checks |
 | `graspful_describe_course` | No | Course statistics |
-| `graspful_create_brand` | No | Generate brand YAML |
+| `graspful_create_brand` | No | Generate brand YAML (required — every org needs a brand) |
 | `graspful_import_course` | **Yes** | Import course to platform (set `GRASPFUL_API_KEY` first) |
 | `graspful_publish_course` | **Yes** | Publish a draft course (set `GRASPFUL_API_KEY` first) |
-| `graspful_import_brand` | **Yes** | Import brand config (set `GRASPFUL_API_KEY` first) |
+| `graspful_import_brand` | **Yes** | Import brand config — required for site to work (set `GRASPFUL_API_KEY` first) |
 | `graspful_list_courses` | **Yes** | List org courses (set `GRASPFUL_API_KEY` first) |
 
 Tools marked "No" for auth work offline — no account needed. Tools marked **Yes** will fail with a clear error if you haven't authenticated. Run `graspful register`, then restart MCP with `GRASPFUL_API_KEY`.
@@ -160,7 +160,17 @@ When building a course from a PDF or document:
 4. For visual content (photos, diagrams, comparisons), find or request publicly accessible image URLs and use `image` content blocks
 5. Do not copy-paste prose verbatim — rewrite for the lesson pattern (instruction -> worked example -> problems)
 
-### Step 4: Brand (optional)
+### Step 4: Create or update the brand
+
+Every org needs a brand for the site to work. Registration creates a minimal default, 
+but you should update it with content relevant to the course topic.
+
+Use `graspful_create_brand` to generate a brand YAML tailored to the course topic, 
+then import it with `graspful_import_brand`. This updates the landing page headline, 
+features, and SEO to match the actual course content.
+
+If the org already has a brand (from registration), importing a new one updates it 
+in place (upsert by slug).
 
 Create a white-label landing page and theme:
 

apps/web/e2e/agent-pipeline-e2e.spec.ts

@@ -357,6 +357,44 @@ test.describe.serial(
       expect(body.orgSlug).toBe(creatorOrgSlug);
     });
 
+    // ── Step 2b: Brand quality — not placeholder garbage ────────────
+    test("step 2b: brand landing content is not placeholder garbage", async ({
+      request,
+    }) => {
+      const domain = `${creatorOrgSlug}.graspful.ai`;
+
+      const res = await request.get(
+        `${BACKEND_URL}/brands/by-domain/${domain}`,
+        { headers: { "Content-Type": "application/json" } }
+      );
+
+      if (res.status() === 404) {
+        // Brand not yet created — skip (will be verified after import)
+        return;
+      }
+
+      expect(res.status()).toBe(200);
+
+      const brand = await res.json();
+
+      // Brand name should NOT equal the raw slug
+      expect(brand.name).not.toBe(creatorOrgSlug);
+
+      // Brand name should be title-cased (not lowercase with spaces)
+      expect(brand.name).not.toBe(creatorOrgSlug.replace(/-/g, ' '));
+
+      // Landing hero headline should NOT be the raw slug
+      const headline = brand.landing?.hero?.headline;
+      expect(headline).toBeTruthy();
+      expect(headline).not.toBe(creatorOrgSlug);
+      expect(headline).not.toBe(creatorOrgSlug.replace(/-/g, ' '));
+      expect(headline.length).toBeGreaterThanOrEqual(10);
+
+      // Brand tagline should be at least 10 characters
+      expect(brand.tagline).toBeTruthy();
+      expect(brand.tagline.length).toBeGreaterThanOrEqual(10);
+    });
+
     // ── Step 3: Scaffold — verify skeleton structure ───────────────
     test("step 3: scaffold produces valid skeleton structure", async () => {
       // We construct the YAML directly (most reliable).

backend/src/auth/auth-register.controller.spec.ts

@@ -118,7 +118,7 @@ describe('RegistrationService', () => {
     expect(mockTx.organization.create).toHaveBeenCalledWith({
       data: {
         slug: 'will-example',
-        name: 'will example',
+        name: 'Will Example',
         niche: 'general',
       },
     });

backend/src/auth/provision.service.ts

@@ -2,6 +2,14 @@ import { Injectable, Logger } from '@nestjs/common';
 import { PrismaService } from '@/prisma/prisma.service';
 import { VercelDomainsService } from '@/shared/application/vercel-domains.service';
 
+/**
+ * Convert a slug like "will-use-case-selling-posthog" to "Will Use Case Selling Posthog".
+ * Used as a fallback when the org name would otherwise be the raw slug with spaces.
+ */
+function humanizeSlug(slug: string): string {
+  return slug.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
 /**
  * Ensures every authenticated user has a personal organization and brand.
  * Called by POST /auth/provision after Supabase Auth sign-up
@@ -47,7 +55,7 @@ export class ProvisionService {
     const clash = await this.prisma.organization.findUnique({ where: { slug: orgSlug } });
     if (clash) orgSlug = `${orgSlug}-${Date.now().toString(36).slice(-4)}`;
 
-    const orgName = orgSlug.replace(/-/g, ' ');
+    const orgName = humanizeSlug(orgSlug);
 
     const result = await this.prisma.$transaction(async (tx) => {
       const org = await tx.organization.create({
@@ -61,39 +69,25 @@ export class ProvisionService {
       // Default brand so the org is accessible via the web UI.
       // Uses upsert for idempotency in case a brand with this slug already exists.
       const domain = `${orgSlug}.graspful.ai`;
+      const brandData = {
+        name: orgName,
+        domain,
+        tagline: `Adaptive learning by ${orgName}`,
+        logoUrl: '/icon.svg',
+        orgSlug,
+        theme: { preset: 'indigo', radius: '0.5rem' },
+        landing: {
+          hero: { headline: `Welcome to ${orgName}`, subheadline: 'Adaptive learning that meets you where you are', ctaText: 'Start Learning' },
+          features: { heading: 'Features', items: [] },
+          howItWorks: { heading: 'How it works', items: [] },
+          faq: [],
+        },
+        seo: { title: orgName, description: `Adaptive learning by ${orgName}`, keywords: [] },
+      };
       await tx.brand.upsert({
         where: { slug: orgSlug },
-        update: {
-          name: orgName,
-          domain,
-          tagline: 'Adaptive learning',
-          logoUrl: '/icon.svg',
-          orgSlug,
-          theme: { preset: 'indigo', radius: '0.5rem' },
-          landing: {
-            hero: { headline: orgName, subheadline: 'Adaptive learning', ctaText: 'Start Learning' },
-            features: { heading: 'Features', items: [] },
-            howItWorks: { heading: 'How it works', items: [] },
-            faq: [],
-          },
-          seo: { title: orgName, description: 'Adaptive learning', keywords: [] },
-        },
-        create: {
-          slug: orgSlug,
-          name: orgName,
-          domain,
-          tagline: 'Adaptive learning',
-          logoUrl: '/icon.svg',
-          orgSlug,
-          theme: { preset: 'indigo', radius: '0.5rem' },
-          landing: {
-            hero: { headline: orgName, subheadline: 'Adaptive learning', ctaText: 'Start Learning' },
-            features: { heading: 'Features', items: [] },
-            howItWorks: { heading: 'How it works', items: [] },
-            faq: [],
-          },
-          seo: { title: orgName, description: 'Adaptive learning', keywords: [] },
-        },
+        update: brandData,
+        create: { slug: orgSlug, ...brandData },
       });
 
       return { orgSlug: org.slug, orgId: org.id };

backend/src/auth/registration.service.ts

@@ -6,6 +6,14 @@ import { VercelDomainsService } from '@/shared/application/vercel-domains.servic
 import { ApiKeyService } from './api-key/api-key.service';
 import * as crypto from 'crypto';
 
+/**
+ * Convert a slug like "will-use-case-selling-posthog" to "Will Use Case Selling Posthog".
+ * Used as a fallback when the org name would otherwise be the raw slug with spaces.
+ */
+function humanizeSlug(slug: string): string {
+  return slug.split('-').map(w => w.charAt(0).toUpperCase() + w.slice(1)).join(' ');
+}
+
 @Injectable()
 export class RegistrationService {
   private readonly logger = new Logger(RegistrationService.name);
@@ -62,7 +70,7 @@ export class RegistrationService {
     let orgSlug = this.emailToOrgSlug(email);
     const existing = await this.prisma.organization.findUnique({ where: { slug: orgSlug } });
     if (existing) orgSlug = `${orgSlug}-${Date.now().toString(36).slice(-4)}`;
-    const orgName = orgSlug.replace(/-/g, ' ');
+    const orgName = humanizeSlug(orgSlug);
 
     // 3. Create DB records
     // Note: Supabase has an AFTER INSERT trigger on auth.users that auto-creates
@@ -81,39 +89,25 @@ export class RegistrationService {
         // This is a placeholder — it gets replaced when the user imports a brand YAML.
         // Uses upsert for idempotency in case a brand with this slug already exists.
         const domain = `${orgSlug}.graspful.ai`;
+        const brandData = {
+          name: orgName,
+          domain,
+          tagline: `Adaptive learning by ${orgName}`,
+          logoUrl: '/icon.svg',
+          orgSlug,
+          theme: { preset: 'indigo', radius: '0.5rem' },
+          landing: {
+            hero: { headline: `Welcome to ${orgName}`, subheadline: 'Adaptive learning that meets you where you are', ctaText: 'Start Learning' },
+            features: { heading: 'Features', items: [] },
+            howItWorks: { heading: 'How it works', items: [] },
+            faq: [],
+          },
+          seo: { title: orgName, description: `Adaptive learning by ${orgName}`, keywords: [] },
+        };
         await tx.brand.upsert({
           where: { slug: orgSlug },
-          update: {
-            name: orgName,
-            domain,
-            tagline: 'Adaptive learning',
-            logoUrl: '/icon.svg',
-            orgSlug,
-            theme: { preset: 'indigo', radius: '0.5rem' },
-            landing: {
-              hero: { headline: orgName, subheadline: 'Adaptive learning', ctaText: 'Start Learning' },
-              features: { heading: 'Features', items: [] },
-              howItWorks: { heading: 'How it works', items: [] },
-              faq: [],
-            },
-            seo: { title: orgName, description: 'Adaptive learning', keywords: [] },
-          },
-          create: {
-            slug: orgSlug,
-            name: orgName,
-            domain,
-            tagline: 'Adaptive learning',
-            logoUrl: '/icon.svg',
-            orgSlug,
-            theme: { preset: 'indigo', radius: '0.5rem' },
-            landing: {
-              hero: { headline: orgName, subheadline: 'Adaptive learning', ctaText: 'Start Learning' },
-              features: { heading: 'Features', items: [] },
-              howItWorks: { heading: 'How it works', items: [] },
-              faq: [],
-            },
-            seo: { title: orgName, description: 'Adaptive learning', keywords: [] },
-          },
+          update: brandData,
+          create: { slug: orgSlug, ...brandData },
         });
 
         // Create API key inside the transaction so it can see the uncommitted org