Clarify public surface handoffs

docs/ops/HYPERTWIST_PUBLIC_WEBSITE_CONTENT_AND_OPERATOR_MANUAL_PACKET_2026-06-22.md

@@ -302,6 +302,24 @@ That follow-up stayed green under:
   - `Quality: 6138`
   - `All rules pass`
 
+Latest public-manual clarity follow-up later on `2026-06-24`:
+
+- the homepage, About, Pricing, Download, and Support pages now share a direct
+  `Choose the right HyperTwist surface` section
+- that guide answers the recurring operator question more plainly than the
+  larger surface matrix alone:
+  - stay on the public website
+  - move into the protected dashboard
+  - use the desktop runtime
+- each card now also carries a direct next action so the browser-versus-
+  desktop split is actionable instead of only descriptive
+
+That follow-up stayed green under:
+
+- `npm --prefix website test -- --run src/__tests__/public-marketing-pages.test.tsx`
+  - `1` test file passed
+  - `12` tests passed
+
 Latest authority-sync follow-up later on `2026-06-23`:
 
 - the public manual stayed aligned with the newer native

website/src/__tests__/public-marketing-pages.test.tsx

@@ -243,6 +243,7 @@ describe('public marketing pages', () => {
     expect(screen.getByText('Operator checkout URL: missing')).toBeTruthy()
     expect(screen.getByText('Current packaged desktop proof')).toBeTruthy()
     expect(screen.getByText('How the release lane works')).toBeTruthy()
+    expect(screen.getByText('Choose the right HyperTwist surface')).toBeTruthy()
     expect(screen.getByText('First launch and desktop setup')).toBeTruthy()
     expect(screen.getByText('Digital delivery workflow')).toBeTruthy()
     expect(screen.getByText('Protected entitlement handoff')).toBeTruthy()
@@ -411,6 +412,8 @@ describe('public marketing pages', () => {
     expect(screen.getByText('Current packaged desktop proof')).toBeTruthy()
     expect(screen.getByText('Packaged validation passed')).toBeTruthy()
     expect(screen.getByText('How a real first session flows')).toBeTruthy()
+    expect(screen.getByText('Choose the right HyperTwist surface')).toBeTruthy()
+    expect(screen.getByText('Move into the protected dashboard')).toBeTruthy()
     expect(screen.getAllByText('Current surface authority map').length).toBeGreaterThan(0)
     expect(screen.getAllByText('Native Unreal desktop runtime').length).toBeGreaterThan(0)
   })
@@ -518,6 +521,8 @@ describe('public marketing pages', () => {
     renderWithProviders(<AboutPage />, ['/about'])
 
     expect(screen.getByText('How a real HyperTwist session unfolds')).toBeTruthy()
+    expect(screen.getByText('Choose the right HyperTwist surface')).toBeTruthy()
+    expect(screen.getByText('Stay on the public website')).toBeTruthy()
     expect(screen.getByText('Current desktop control and XR truth')).toBeTruthy()
     expect(screen.getByText('Selectable control and settings roster')).toBeTruthy()
     expect(screen.getByText('Shipped classic control profile')).toBeTruthy()
@@ -810,6 +815,8 @@ describe('public marketing pages', () => {
     expect(screen.getByText('$99 / month')).toBeTruthy()
     expect(screen.getByText('Current packaged desktop proof')).toBeTruthy()
     expect(screen.getAllByText('What happens after access is granted').length).toBeGreaterThan(0)
+    expect(screen.getByText('Choose the right HyperTwist surface')).toBeTruthy()
+    expect(screen.getByText('Use the desktop runtime')).toBeTruthy()
     expect(screen.getByText('Shows account, auth, billing, and release readiness posture')).toBeTruthy()
     expect(screen.getByText('Owns recognition, replay, coaching, and packaged training behavior')).toBeTruthy()
     expect(screen.getByText('Commercial distribution doctrine')).toBeTruthy()
@@ -894,6 +901,7 @@ describe('public marketing pages', () => {
     expect(screen.getByText('If the desktop app is primary, why keep the web version?')).toBeTruthy()
     expect(screen.getByText('Is VR/controller support already fully finished?')).toBeTruthy()
     expect(screen.getByText('Do higher-dimensional selector choices persist between sessions?')).toBeTruthy()
+    expect(screen.getByText('Choose the right HyperTwist surface')).toBeTruthy()
     expect(screen.getByText('Browser and desktop responsibilities')).toBeTruthy()
     expect(screen.getByText('Shows account, auth, billing, and release readiness posture')).toBeTruthy()
     expect(screen.getByText('Support lanes')).toBeTruthy()

website/src/pages/public-page-helpers.tsx

@@ -189,6 +189,80 @@ export function DeliverySurfaceResponsibilitiesGrid({ limit }: { limit?: number
   )
 }
 
+const surfaceChoiceGuideCards = [
+  {
+    title: 'Stay on the public website',
+    posture: 'Public release shell',
+    description: 'Use this surface when you are still evaluating HyperTwist, reading docs, checking launch posture, or reviewing pricing, notices, and rollout guidance.',
+    bullets: [
+      'Best for product discovery, public documentation, pricing, support, and legal follow-through.',
+      'Keeps launch-readiness and packaged-proof posture visible without exposing protected download authority.',
+    ],
+    action: {
+      to: '/docs',
+      label: 'Open public manual',
+    },
+  },
+  {
+    title: 'Move into the protected dashboard',
+    posture: 'Signed-in operator shell',
+    description: 'Use this surface when identity, entitlement, billing, protected notices, or browser-to-desktop pairing starts to matter.',
+    bullets: [
+      'Best for account state, protected downloads, desktop-link pairing, and release-manifest viewer truth.',
+      'Keeps the operator inside direct signed-in routes instead of routing them back through anonymous guidance.',
+    ],
+    action: {
+      to: '/app',
+      label: 'Open operator dashboard',
+    },
+  },
+  {
+    title: 'Use the desktop runtime',
+    posture: 'Simulator authority',
+    description: 'Use this surface when you need the actual training loop, packaged higher-dimensional maps, replay/coaching behavior, or simulator-side diagnostics.',
+    bullets: [
+      'Best for classic-cube execution, dedicated-family Magic120Cell and MagicCube5D work, and packaged validation truth.',
+      'Owns the real simulator behavior that the public and protected browser surfaces intentionally do not claim.',
+    ],
+    action: {
+      to: '/download',
+      label: 'Open download center',
+    },
+  },
+] as const
+
+export function SurfaceChoiceGuideSection({
+  title = 'Choose the right HyperTwist surface',
+  description,
+}: {
+  title?: string
+  description?: string
+}) {
+  return (
+    <Section title={title} description={description}>
+      <div className="card-grid">
+        {surfaceChoiceGuideCards.map((card) => (
+          <article key={card.title} className="card">
+            <p className="status-pill status-pill--info">{card.posture}</p>
+            <h3>{card.title}</h3>
+            <p>{card.description}</p>
+            <ul className="list top-gap">
+              {card.bullets.map((bullet) => (
+                <li key={bullet}>{bullet}</li>
+              ))}
+            </ul>
+            <div className="button-row top-gap">
+              <Link className="button button--ghost" to={card.action.to}>
+                {card.action.label}
+              </Link>
+            </div>
+          </article>
+        ))}
+      </div>
+    </Section>
+  )
+}
+
 export function PublicPackagedDesktopProofSection({
   platform,
   actions = [],

website/src/pages/public-pages-commerce.tsx

@@ -39,6 +39,7 @@ import {
   releaseCommerceFallback,
   Section,
   studioFallbackPlan,
+  SurfaceChoiceGuideSection,
   usePublicReleaseManifestView,
 } from './public-page-helpers'
 
@@ -137,6 +138,8 @@ export function PricingPage() {
           </div>
         </Section>
 
+        <SurfaceChoiceGuideSection description="This keeps pricing honest about what should happen next: stay public for plan comparison, move protected for account-aware access, and move native for the actual simulator." />
+
         <Section
           title="Why plans live in the browser while training stays native"
           description="Commercial access, entitlement, and launch-readiness posture belong to the browser shell so the simulator can stay focused on training quality."
@@ -313,6 +316,8 @@ export function DownloadPage() {
           </div>
         </Section>
 
+        <SurfaceChoiceGuideSection description="Download posture is clearer when the current best surface is explicit: public for target and release context, protected for entitlement, and desktop for the real training runtime." />
+
         <Section
           title="First launch and desktop setup"
           description="This keeps the download page useful after the archive is in hand: what to verify, how to pair the app, and which current runtime lanes matter first."

website/src/pages/public-pages-marketing.tsx

@@ -37,6 +37,7 @@ import {
   DeliverySurfaceResponsibilitiesGrid,
   PublicPackagedDesktopProofSection,
   Section,
+  SurfaceChoiceGuideSection,
   supportTopicDirectory,
   supportTopicGuidance,
   usePublicReleaseManifestView,
@@ -416,6 +417,8 @@ export function HomeLanding() {
           </div>
         </Section>
 
+        <SurfaceChoiceGuideSection description="This is the shortest practical answer to the browser-versus-desktop question: stay public for release-safe context, move protected for account-aware release work, and move native for the actual simulator." />
+
         <Section
           title="Current surface authority map"
           description="HyperTwist really has five distinct surfaces today. This shared map keeps the public site, embedded browser shell, protected dashboard, desktop runtime, and frozen browser-client branch from being blurred together."
@@ -496,6 +499,8 @@ export function AboutPage() {
           </div>
         </Section>
 
+        <SurfaceChoiceGuideSection description="Keeping the website and the desktop build together only makes sense if the handoff is explicit. This guide keeps the right surface choice visible in plain language." />
+
         <Section
           title="Current desktop control and XR truth"
           description="The product can be ambitious without overclaiming. This page now makes the current input, controller, and XR posture explicit."
@@ -985,6 +990,8 @@ export function SupportPage() {
           </div>
         </Section>
 
+        <SurfaceChoiceGuideSection description="Most support confusion disappears once the operator picks the right surface first: public for guidance, protected for account-aware release work, desktop for simulator execution." />
+
         <Section
           title="Browser and desktop responsibilities"
           description="This keeps support conversations anchored to the real live surfaces so operators know whether they need public guidance, protected account posture, or native runtime follow-through."

website/src/site-data.ts

@@ -762,6 +762,11 @@ export const resourceCollections = [
 ] as const
 
 export const changelogEntries = [
+  {
+    date: 'June 24, 2026',
+    title: 'Key public pages now answer which HyperTwist surface to use next',
+    details: 'The homepage, About, Pricing, Download, and Support pages now share a direct surface-choice guide for the public website, protected dashboard, and native desktop runtime, so operators no longer have to infer the browser-versus-desktop handoff only from deeper matrix or FAQ sections.',
+  },
   {
     date: 'June 24, 2026',
     title: 'Protected dashboard and downloads now keep the same help-lane split after sign-in',