@woodsportal/hubspot-kit 1.0.41 → 1.0.42-dev.0

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/resolve-post-login-path.ts

@@ -0,0 +1,21 @@
+import { Routes } from '@/config/routes'
+import { isBlockedPostLoginPath } from '@/features/auth/post-login-path'
+import { normalizeRouterPath } from '@/utils/normalize-router-path'
+import type { SafeAuthRouter } from '@/utils/safe-router-navigation'
+
+export type PostLoginRouter = SafeAuthRouter & {
+  state: {
+    location?: {
+      search?: { r?: string; [key: string]: string | undefined }
+      pathname?: string
+    }
+  }
+}
+
+export function resolvePostLoginPath(router: PostLoginRouter): string {
+  const redirect = router.state.location?.search?.r
+  if (redirect && !isBlockedPostLoginPath(String(redirect))) {
+    return normalizeRouterPath(String(redirect))
+  }
+  return Routes.portal
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/use-portal-session.ts

@@ -0,0 +1,25 @@
+import { useEffect, useMemo, useState } from 'react'
+import { AUTH_SESSION_CHANGED } from '@/features/auth/auth-session-events'
+import { isFullyAuthenticatedSession, isMfaPendingSession } from '@/features/auth/auth-session'
+
+function useAuthSessionRevision(): number {
+  const [revision, setRevision] = useState(0)
+  useEffect(() => {
+    const bump = () => setRevision((value) => value + 1)
+    window.addEventListener(AUTH_SESSION_CHANGED, bump)
+    return () => window.removeEventListener(AUTH_SESSION_CHANGED, bump)
+  }, [])
+  return revision
+}
+
+export { useAuthSessionRevision }
+
+export function usePortalSession(): boolean {
+  const revision = useAuthSessionRevision()
+  return useMemo(() => isFullyAuthenticatedSession(), [revision])
+}
+
+export function useIsMfaPendingSession(): boolean {
+  const revision = useAuthSessionRevision()
+  return useMemo(() => isMfaPendingSession(), [revision])
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/auth/use-signed-in-email.ts

@@ -0,0 +1,55 @@
+import { useEffect, useState } from 'react'
+
+import { api } from '@/integrations/woodsportal-sdk'
+import { getStoredLoginEmail } from '@/features/auth/login-email-storage'
+import { usePortalSession } from '@/features/auth/use-portal-session'
+
+function readEmailFromProfile(data: unknown): string | null {
+  if (data == null || typeof data !== 'object') {
+    return null
+  }
+  const root = data as Record<string, unknown>
+  const profile = (root.data ?? root) as Record<string, unknown>
+  const email = profile.email
+  return typeof email === 'string' && email.trim() !== '' ? email.trim() : null
+}
+
+export function useSignedInEmail(): { email: string | null; isLoading: boolean } {
+  const isAuthenticated = usePortalSession()
+  const [email, setEmail] = useState<string | null>(() => getStoredLoginEmail())
+  const [isLoading, setIsLoading] = useState(false)
+
+  useEffect(() => {
+    if (!isAuthenticated) {
+      setEmail(null)
+      setIsLoading(false)
+      return
+    }
+
+    const stored = getStoredLoginEmail()
+    if (stored) {
+      setEmail(stored)
+      return
+    }
+
+    setIsLoading(true)
+    const { me } = api.auth.me({
+      onSuccess: (data) => {
+        setEmail(readEmailFromProfile(data) ?? getStoredLoginEmail())
+        setIsLoading(false)
+      },
+      onError: () => {
+        setEmail(getStoredLoginEmail())
+        setIsLoading(false)
+      },
+      onLoadingChange: (loading) => {
+        if (!loading) {
+          setIsLoading(false)
+        }
+      },
+    })
+    void me()
+  }, [isAuthenticated])
+
+  return { email, isLoading }
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/components/starter-guide-page.tsx

@@ -0,0 +1,218 @@
+import { SectionCard } from '@/components/layout/section-card'
+import { Link } from '@/components/ui/link'
+import { AUTH_SCAFFOLD_TIER } from '@/config/auth-tier'
+import { NAV_SCAFFOLD_MODE } from '@/config/nav-scaffold'
+import { Routes } from '@/config/routes'
+import {
+  AUTH_BOOT_STEPS,
+  AUTH_ENV_VARS,
+  AUTH_INIT_EXAMPLES,
+  AUTH_NAV_EXAMPLES,
+  PAGE_SCAFFOLD_EXAMPLES,
+  AUTH_PROJECT_PATHS,
+  AUTH_TIER_DESCRIPTION,
+  PORTAL_AUTH_VS_HUBSPOT,
+  authRoutesForTier,
+} from '@/features/starter/content/auth-guide-content'
+import {
+  DEV_WORKFLOW,
+  PROJECT_LAYOUT,
+  WOODSCLI_ABOUT,
+  WOODSCLI_COMMANDS,
+} from '@/features/starter/content/woodscli-guide-content'
+import { StarterPageFrame } from '@/features/starter/components/starter-page-frame'
+
+export function StarterGuidePage() {
+  const tier = AUTH_SCAFFOLD_TIER
+  const routes = authRoutesForTier(tier)
+
+  return (
+    <StarterPageFrame
+      className="max-w-4xl"
+      title="Developer guide"
+      description={
+        <>
+          WoodsCLI module with portal auth (<strong>{tier}</strong> tier). Use this page for
+          commands, project layout, and auth wiring — then replace the starter features with your CRM
+          UI under <code className="rounded bg-gray-100 px-1 text-xs">src/features/</code>.
+        </>
+      }
+    >
+      <div className="space-y-6">
+        <SectionCard title={`Portal auth — ${tier} tier`}>
+          <p className="text-sm leading-relaxed text-[#516f90]">{AUTH_TIER_DESCRIPTION[tier]}</p>
+          <ul className="mt-4 list-disc space-y-2 pl-5 text-sm text-[#516f90]">
+            <li>
+              <Link to={Routes.login}>Sign in</Link> at <code className="font-mono text-xs">/#/login</code>{' '}
+              (posts <code className="font-mono text-xs">username</code> + password to{' '}
+              <code className="font-mono text-xs">/api/auth/login</code>).
+            </li>
+            <li>
+              After login, visit the protected sample at{' '}
+              <Link to={Routes.portal}>/portal</Link> — session + profile via{' '}
+              <code className="font-mono text-xs">GET /api/auth/me</code>.
+            </li>
+            <li>
+              Set <code className="font-mono text-xs">VITE_PUBLIC_REST_API_ENDPOINT</code> in{' '}
+              <code className="font-mono text-xs">.env.local</code> after{' '}
+              <code className="font-mono text-xs">wp setup</code>.
+            </li>
+          </ul>
+          <p className="mt-4 text-xs text-[#516f90]">
+            Re-scaffold:{' '}
+            <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">{AUTH_INIT_EXAMPLES[tier]}</code>
+          </p>
+        </SectionCard>
+
+        <SectionCard title={`Navigation — ${NAV_SCAFFOLD_MODE} shell`}>
+          <p className="text-sm leading-relaxed text-[#516f90]">
+            Menu links come from{' '}
+            <code className="rounded bg-gray-100 px-1 text-xs">src/config/portal-nav.ts</code> — edit
+            once for both top nav and sidebar layouts.
+          </p>
+          <p className="mt-4 text-xs text-[#516f90]">
+            Sidebar init:{' '}
+            <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">
+              {AUTH_NAV_EXAMPLES.sidebar}
+            </code>
+          </p>
+          <ul className="mt-4 space-y-2 text-xs text-[#516f90]">
+            {PAGE_SCAFFOLD_EXAMPLES.map((cmd) => (
+              <li key={cmd}>
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono">{cmd}</code>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Auth routes (this tier)">
+          <ul className="divide-y divide-[#eaf0f6]">
+            {routes.map(({ path, access }) => (
+              <li key={path} className="flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:flex-row sm:gap-4">
+                <code className="shrink-0 rounded bg-[#eaf0f6] px-2 py-1 font-mono text-xs text-[#0091ae]">
+                  {path}
+                </code>
+                <span className="text-sm leading-relaxed text-[#516f90]">{access}</span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Two auth concepts">
+          <ul className="space-y-4">
+            {PORTAL_AUTH_VS_HUBSPOT.map(({ label, cmds, purpose }) => (
+              <li key={label}>
+                <h3 className="text-sm font-medium text-[#33475b]">{label}</h3>
+                <p className="mt-1 font-mono text-xs text-[#0091ae]">{cmds}</p>
+                <p className="mt-1 text-sm leading-relaxed text-[#516f90]">{purpose}</p>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Environment (.env.local)">
+          <ul className="space-y-3">
+            {AUTH_ENV_VARS.map(({ name, note }) => (
+              <li key={name} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {name}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Session boot order">
+          <ol className="list-decimal space-y-2 pl-5 text-sm leading-relaxed text-[#516f90]">
+            {AUTH_BOOT_STEPS.map((step) => (
+              <li key={step}>{step}</li>
+            ))}
+          </ol>
+        </SectionCard>
+
+        <SectionCard title="About WoodsCLI">
+          <p className="text-sm leading-relaxed text-[#516f90]">{WOODSCLI_ABOUT.tagline}</p>
+          <p className="mt-3 text-sm leading-relaxed text-[#516f90]">{WOODSCLI_ABOUT.docsHint}</p>
+        </SectionCard>
+
+        <SectionCard title="Essential commands">
+          <ul className="divide-y divide-[#eaf0f6]">
+            {WOODSCLI_COMMANDS.map(({ cmd, desc }) => (
+              <li key={cmd} className="flex flex-col gap-1 py-3 first:pt-0 last:pb-0 sm:flex-row sm:gap-4">
+                <code className="shrink-0 rounded bg-[#eaf0f6] px-2 py-1 font-mono text-xs text-[#0091ae]">
+                  {cmd}
+                </code>
+                <span className="text-sm leading-relaxed text-[#516f90]">{desc}</span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Auth-related paths">
+          <ul className="space-y-3">
+            {AUTH_PROJECT_PATHS.map(({ path, note }) => (
+              <li key={path} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {path}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Project layout">
+          <ul className="space-y-3">
+            {PROJECT_LAYOUT.map(({ path, note }) => (
+              <li key={path} className="text-sm leading-relaxed">
+                <code className="rounded bg-[#eaf0f6] px-1.5 py-0.5 font-mono text-xs text-[#33475b]">
+                  {path}
+                </code>
+                <span className="mt-1 block text-[#516f90] sm:mt-0 sm:inline sm:before:content-['—_']">
+                  {note}
+                </span>
+              </li>
+            ))}
+          </ul>
+        </SectionCard>
+
+        <SectionCard title="Developer workflow">
+          <ol className="space-y-4">
+            <li>
+              <h3 className="text-sm font-medium text-[#33475b]">0 · Verify portal login</h3>
+              <p className="mt-1 text-sm leading-relaxed text-[#516f90]">
+                Run <code className="font-mono text-xs">wp dev</code>, open{' '}
+                <Link to={Routes.login}>/#/login</Link>, and confirm you reach{' '}
+                <Link to={Routes.portal}>/portal</Link> with an active session before building CRM
+                features.
+              </p>
+            </li>
+            {DEV_WORKFLOW.map(({ title: stepTitle, body }) => (
+              <li key={stepTitle}>
+                <h3 className="text-sm font-medium text-[#33475b]">{stepTitle}</h3>
+                <p className="mt-1 text-sm leading-relaxed text-[#516f90]">{body}</p>
+              </li>
+            ))}
+          </ol>
+        </SectionCard>
+
+        <SectionCard title="Routing & customization">
+          <p className="text-sm leading-relaxed text-[#516f90]">
+            File routes live under <code className="font-mono text-xs">src/routes/</code> and delegate
+            to <code className="font-mono text-xs">src/features/</code>. Hash history is the default
+            for HubSpot CMS embeds. Add protected routes with{' '}
+            <code className="font-mono text-xs">beforeLoad: {'() => ({ requiresAuth: true })'}</code>.
+            Replace <code className="font-mono text-xs">src/features/starter/</code> when you outgrow
+            the demo. Kit docs:{' '}
+            <code className="font-mono text-xs">node_modules/@woodsportal/hubspot-kit/docs/AUTH-SCAFFOLD.md</code>.
+          </p>
+        </SectionCard>
+      </div>
+    </StarterPageFrame>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/components/starter-home-page.tsx

@@ -0,0 +1,21 @@
+import { Link } from '@tanstack/react-router'
+
+import { ROUTES } from '@/config/routes'
+
+import { StarterHome } from './starter-home'
+
+export function StarterHomePage() {
+  return (
+    <>
+      <StarterHome />
+      <div className="mx-auto max-w-4xl px-6 pb-10 sm:px-10">
+        <Link
+          to={ROUTES.guide}
+          className="inline-flex items-center rounded-md bg-[#0091ae] px-4 py-2 text-sm font-semibold text-white shadow-sm hover:bg-[#007a8c]"
+        >
+          Open developer guide →
+        </Link>
+      </div>
+    </>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/components/starter-home.tsx

@@ -0,0 +1,48 @@
+import { useStarterPreview } from '../hooks/use-starter-preview'
+import { STARTER_FEATURES, WOODSCLI_ABOUT } from '../content/woodscli-guide-content'
+
+export function StarterHome() {
+  const { title, tagline, showFeatureCards, heroStyle } = useStarterPreview()
+
+  return (
+    <>
+      <section
+        className={
+          heroStyle === 'minimal'
+            ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[var(--mc-bg-shell,#f5f8fa)] text-[var(--mc-text,#33475b)] border-b border-[var(--mc-border,#cbd6e2)]'
+            : heroStyle === 'bold'
+              ? 'px-6 py-14 sm:px-10 sm:py-16 bg-[#1c1c1f] text-white'
+              : 'px-6 py-14 sm:px-10 sm:py-16 bg-gradient-to-br from-[var(--primary-color,#FF7A59)] to-[var(--secondary-color,#2797AF)] text-white'
+        }
+      >
+        <div className="mx-auto max-w-4xl">
+          <p className="mb-2 text-xs font-semibold uppercase tracking-widest opacity-80">
+            {WOODSCLI_ABOUT.package} · local dev
+          </p>
+          <h1 className="text-3xl font-semibold tracking-tight sm:text-4xl">{title}</h1>
+          <p className="mt-4 max-w-2xl text-base leading-relaxed opacity-90 sm:text-lg">{tagline}</p>
+          <p className="mt-6 text-sm opacity-75">
+            Module config overlay:{' '}
+            <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">Ctrl+Shift+Z</kbd>
+            {' · '}
+            Mac: <kbd className="rounded bg-black/10 px-1.5 py-0.5 font-mono text-xs">⌃⇧Z</kbd>
+          </p>
+        </div>
+      </section>
+
+      {showFeatureCards ? (
+        <div className="mx-auto grid max-w-4xl gap-4 px-6 py-10 sm:grid-cols-3 sm:px-10">
+          {STARTER_FEATURES.map((feature) => (
+            <article
+              key={feature.title}
+              className="rounded-lg border border-[#cbd6e2] bg-white p-5 shadow-sm"
+            >
+              <h2 className="text-sm font-semibold text-[var(--primary-color,#FF7A59)]">{feature.title}</h2>
+              <p className="mt-2 text-sm leading-relaxed text-[#516f90]">{feature.body}</p>
+            </article>
+          ))}
+        </div>
+      ) : null}
+    </>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/components/starter-page-frame.tsx

@@ -0,0 +1,25 @@
+import type { ReactNode } from 'react'
+
+type StarterPageFrameProps = {
+  title: string
+  description?: ReactNode
+  children?: ReactNode
+  className?: string
+}
+
+export function StarterPageFrame({
+  title,
+  description,
+  children,
+  className = 'max-w-2xl',
+}: StarterPageFrameProps) {
+  return (
+    <div className={`mx-auto space-y-4 ${className}`}>
+      <div>
+        <h1 className="text-2xl font-semibold text-gray-900">{title}</h1>
+        {description ? <p className="mt-2 text-gray-600">{description}</p> : null}
+      </div>
+      {children}
+    </div>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/components/starter-protected-page.tsx

@@ -0,0 +1,54 @@
+import { useRouter } from '@tanstack/react-router'
+
+import { Button } from '@/components/ui/Button'
+import { Routes } from '@/config/routes'
+import { clearClientAuthSession } from '@/features/auth/clear-client-auth-session'
+import { useSignedInEmail } from '@/features/auth/use-signed-in-email'
+import { usePortalSession } from '@/features/auth/use-portal-session'
+import { StarterPageFrame } from '@/features/starter/components/starter-page-frame'
+import { api } from '@/integrations/woodsportal-sdk'
+
+export function StarterProtectedPage() {
+  const isAuthenticated = usePortalSession()
+  const { email, isLoading } = useSignedInEmail()
+  const router = useRouter()
+
+  const signedInLabel = isLoading ? 'Loading…' : (email ?? 'Signed in')
+
+  const handleLogout = async () => {
+    clearClientAuthSession()
+    try {
+      const { logout } = api.auth.logout({})
+      await logout()
+    } catch {
+      // local state already cleared
+    }
+    router.navigate({ to: Routes.login })
+  }
+
+  return (
+    <StarterPageFrame
+      title="Protected portal"
+      description={
+        <>
+          You reached <code className="rounded bg-gray-100 px-1">/portal</code> — sample authenticated
+          page for the auth scaffold.
+        </>
+      }
+    >
+      <dl className="rounded-lg border border-gray-200 bg-gray-50 p-4 text-sm">
+        <div className="flex justify-between gap-4">
+          <dt className="text-gray-500">Session</dt>
+          <dd className="font-medium text-gray-900">{isAuthenticated ? 'Active' : 'None'}</dd>
+        </div>
+        <div className="mt-2 flex justify-between gap-4">
+          <dt className="text-gray-500">Signed in as</dt>
+          <dd className="font-medium text-gray-900">{signedInLabel}</dd>
+        </div>
+      </dl>
+      <Button variant="outline" onClick={() => void handleLogout()}>
+        Sign out
+      </Button>
+    </StarterPageFrame>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/components/starter-single-page.tsx

@@ -0,0 +1,17 @@
+import { StarterShell } from '@/components/layout/starter-shell'
+
+import { StarterGuidePage } from './starter-guide-page'
+import { StarterHome } from './starter-home'
+
+/** Single-page starter when `wp init --router none` (no TanStack Router). */
+export function StarterSinglePage() {
+  return (
+    <StarterShell showNav={false}>
+      <StarterHome />
+      <div className="mx-auto max-w-4xl px-6 sm:px-10">
+        <hr className="my-10 border-[#cbd6e2]" />
+      </div>
+      <StarterGuidePage />
+    </StarterShell>
+  )
+}

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/content/auth-guide-content.ts

@@ -0,0 +1,91 @@
+export type AuthTierName = 'starter' | 'sso' | 'full'
+
+export const AUTH_TIER_DESCRIPTION: Record<AuthTierName, string> = {
+  starter: 'Email + password login with a protected /portal sample page.',
+  sso: 'Starter login plus SSO OAuth callback handling at /login/sso.',
+  full: 'SSO plus MFA gate at /two-fa — recommended when the hub enforces 2FA.',
+}
+
+export const AUTH_ENV_VARS = [
+  {
+    name: 'VITE_PUBLIC_REST_API_ENDPOINT',
+    note: 'woodsportal-api base URL (required for login). Example: https://api.dev.woodsportal.com',
+  },
+  {
+    name: 'VITE_DEV_PORTAL_ID',
+    note: 'Optional local dev portal id — sent as X-Dev-Portal-Id when logging in.',
+  },
+  {
+    name: 'VITE_REFRESH_TOKEN',
+    note: 'Cookie name for the refresh token (not the token value). Default: wp.c.auth.refresh',
+  },
+] as const
+
+export const AUTH_BOOT_STEPS = [
+  'mountPortal → syncSdkHubContextFromRuntime',
+  'configureWoodsPortalSdk (woodsportal-client-sdk HTTP client)',
+  'SSO URL normalization (sso / full tiers)',
+  'App bootstrap refresh (existing refresh cookie)',
+  'TanStack Router + PublicRoute / PrivateRoute guards',
+  'MainLayout → api.auth.me() (GET /api/auth/me) when authenticated',
+] as const
+
+export const AUTH_PROJECT_PATHS = [
+  { path: 'src/config/auth-tier.ts', note: 'Scaffold tier patched by wp init (starter | sso | full)' },
+  { path: 'src/config/portal-nav.ts', note: 'Shared nav links for top nav and sidebar layouts' },
+  { path: 'src/config/nav-scaffold.ts', note: 'Nav shell mode patched by wp init (top | sidebar)' },
+  { path: 'src/features/auth/', note: 'Login UI, session bridge, route guards, email storage' },
+  { path: 'src/integrations/configure-woodsportal-sdk.ts', note: 'SDK HTTP init — API URL, cookies, routes' },
+  { path: 'src/integrations/woodsportal-sdk.ts', note: 'Single import surface for api.auth.* and api.crm.*' },
+  { path: 'src/app.tsx', note: 'Session bootstrap before RouterProvider mounts' },
+  { path: 'src/utils/public-route.tsx', note: 'Redirects authenticated users away from /login' },
+  { path: 'src/utils/private-route.tsx', note: 'Protects routes with requiresAuth: true' },
+] as const
+
+export const AUTH_INIT_EXAMPLES: Record<AuthTierName, string> = {
+  starter:
+    'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter -y',
+  sso: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth sso -y',
+  full: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth full -y',
+}
+
+export const AUTH_NAV_EXAMPLES = {
+  top: 'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter -y',
+  sidebar:
+    'npx wp init -t module-hybrid-cdn -n my-portal --router hash --auth starter --nav sidebar -y',
+} as const
+
+export const PAGE_SCAFFOLD_EXAMPLES = [
+  'wp page add settings --protected --nav',
+  'wp page add about --public',
+  'wp page add billing --protected --title "Billing" --no-nav',
+] as const
+
+export function authRoutesForTier(tier: AuthTierName): Array<{ path: string; access: string }> {
+  const routes = [
+    { path: '/guide', access: 'Public — this page' },
+    { path: '/login', access: 'Public — email + password' },
+    { path: '/portal', access: 'Protected — sample page after login' },
+    { path: '/unauthorized', access: 'Public' },
+  ]
+  if (tier === 'sso' || tier === 'full') {
+    routes.splice(2, 0, { path: '/login/sso', access: 'Public — SSO OAuth callback' })
+  }
+  if (tier === 'full') {
+    routes.splice(3, 0, { path: '/two-fa', access: 'Public — MFA OTP gate' })
+  }
+  return routes
+}
+
+export const PORTAL_AUTH_VS_HUBSPOT = [
+  {
+    label: 'HubSpot CLI auth',
+    cmds: 'wp auth · wp portal use',
+    purpose: 'Upload/watch module files to Design Manager',
+  },
+  {
+    label: 'Portal user auth',
+    cmds: 'wp init --auth starter|sso|full',
+    purpose: 'End users sign in via woodsportal-api + woodsportal-client-sdk',
+  },
+] as const

package/examples/greenfield/module-hybrid-cdn-auth-starter/src/features/starter/content/woodscli-guide-content.ts

@@ -0,0 +1,86 @@
+/** Static WoodsCLI developer reference — shown on the wp init starter pages. */
+
+export const WOODSCLI_COMMANDS = [
+  {
+    cmd: 'wp dev',
+    desc: 'Local Vite preview + module-config overlay (this page). Alias: wp local.',
+  },
+  {
+    cmd: 'wp doctor',
+    desc: 'Validate Node, deps, .wphs/, index.html, fields.json, and HubSpot CLI setup.',
+  },
+  {
+    cmd: 'wp build --tier prod',
+    desc: 'Production build (CDN bundle and/or HubSpot module, per projectType).',
+  },
+  {
+    cmd: 'wp deploy --tier prod',
+    desc: 'Build, publish CDN artifacts, and upload the module to HubSpot.',
+  },
+  {
+    cmd: 'wp setup',
+    desc: 'Copy hubspot.config.yml, .env.*, and vite shims from kit templates.',
+  },
+  {
+    cmd: 'wp migrate --yes',
+    desc: 'Move legacy .dev/ or woodsportal.hs.json to .wphs/ + woodscli.json.',
+  },
+] as const
+
+export const PROJECT_LAYOUT = [
+  { path: 'woodscli.json', note: 'Project config — module paths, entries, dev.adapter' },
+  { path: 'public/fields.json', note: 'HubSpot module field schema (Content / Styles tabs)' },
+  { path: '.wphs/', note: 'Local workspace — config, fixtures, kit symlinks (gitignore most)' },
+  { path: 'wphs.adapter.ts', note: 'Syncs module field values → window.__WPHS_DATA__ in dev' },
+  { path: 'src/config/router.ts', note: 'Hash vs browser history — set by wp init (hash = client-frontend)' },
+  { path: 'src/routes/', note: 'TanStack Router file routes (thin — delegate to features/)' },
+  { path: 'src/app.tsx', note: 'RouterProvider shell — same role as woodsportal-client-frontend App' },
+  { path: 'src/features/starter/', note: 'Starter demo UI — replace with your portal features' },
+  { path: 'src/portal/', note: 'Dev vs production mount (mount-dev-preview, mount-portal)' },
+  { path: 'src/integrations/', note: 'Third-party wiring (TanStack Router, SDK, etc.)' },
+  { path: 'src/hubspot/', note: 'HubSpot runtime types and dev fixtures' },
+  { path: 'src/main.tsx', note: 'Dev entry — mounts overlay + routed preview' },
+  { path: 'hubspot.config.yml', note: 'HubSpot CLI portal + PAT (copy from .example)' },
+] as const
+
+export const DEV_WORKFLOW = [
+  {
+    title: '1 · Edit module fields',
+    body: 'Press Ctrl+Shift+Z (Mac ⌃⇧Z) to open the HubSpot-style Content / Styles panel. Changes apply to the preview after you click Apply changes.',
+  },
+  {
+    title: '2 · Iterate in src/',
+    body: 'Add features under src/features/, shared UI under src/components/, and wire HubSpot data via wphs.adapter.ts and public/fields.json.',
+  },
+  {
+    title: '3 · Connect HubSpot',
+    body: 'Copy hubspot.config.yml.example → hubspot.config.yml, add a personal access key, then wp upload or wp watch for CMS sync.',
+  },
+  {
+    title: '4 · Ship',
+    body: 'Hybrid CDN: wp deploy. Monolith: wp build --hubspot-only then wp upload.',
+  },
+] as const
+
+export const WOODSCLI_ABOUT = {
+  package: '@woodsportal/hubspot-kit',
+  tagline:
+    'WoodsCLI is WoodsPortal’s dev kit for HubSpot CMS modules and themes — Vite local preview, fields.json editing, CDN + module build pipelines, and HubSpot CLI integration.',
+  docsHint:
+    'Full command list and guides ship in node_modules/@woodsportal/hubspot-kit/docs/ (CLI-REFERENCE.md, MODULES.md, HUBSPOT-CLI-SETUP.md).',
+} as const
+
+export const STARTER_FEATURES = [
+  {
+    title: 'Module fields',
+    body: 'Content and Styles tabs mirror HubSpot’s module editor. Apply changes to refresh this preview.',
+  },
+  {
+    title: 'Local persistence',
+    body: 'Saved values land in .wphs/config/module-config.local.json — safe to gitignore.',
+  },
+  {
+    title: 'Ship when ready',
+    body: 'Run wp build and wp deploy when your module is ready for HubSpot.',
+  },
+] as const