Ship HyperTwist offline operator manual surface

2026-06-30 10:10:24 +00:00 · 2026-06-30 10:10:24 +00:00 · 2e5cf09d1d
commit 2e5cf09d1d
parent ebbd30abd3
6 changed files with 346 additions and 5 deletions
--- a/website/README.md
+++ b/website/README.md
@ -64,6 +64,9 @@ manual:
 - the docs and resources pages now also carry a practical simulator-use manual
  for recognition, replay, higher-dimensional runtime ownership, and operator
  diagnostics without overclaiming browser or VR parity
+- the website now also ships a same-origin downloadable operator manual at
+  `website/public/manual/hypertwist-operator-manual.md` so the desktop-first
+  onboarding and boundary truth can travel offline with the product
 - the public browser-account method lineup is now also visible on the
  homepage, pricing, download, support, docs, and getting-started routes so
  high-traffic decision pages no longer hide provider truth until the auth
--- a/website/public/manual/hypertwist-operator-manual.md
+++ b/website/public/manual/hypertwist-operator-manual.md
@ -0,0 +1,242 @@
+# HyperTwist Operator Manual
+
+Last updated: 2026-06-30
+
+## Purpose
+
+This manual is the downloadable, public-facing operating guide for HyperTwist.
+It mirrors the current browser, protected-dashboard, and desktop-runtime truth
+without pretending the optional browser-client branch or unfinished XR lane is
+already shipped.
+
+Use this manual when you need one offline reference for:
+
+- first-session onboarding
+- protected dashboard follow-through
+- desktop download and pairing
+- current control roster and runtime settings truth
+- higher-dimensional runtime ownership
+- release, notice, and support follow-through
+
+## Product topology
+
+HyperTwist currently has four practical surfaces:
+
+1. Public website
+   - product overview
+   - docs and route atlas
+   - pricing and launch posture
+   - notices and release references
+2. Protected browser dashboard
+   - account state
+   - entitlement and download posture
+   - browser-to-desktop pairing
+   - protected launch-status and notices follow-through
+3. Native Unreal desktop runtime
+   - real simulator execution
+   - recognition, replay, coaching, and training
+   - packaged runtime behavior
+   - higher-dimensional family ownership
+4. Embedded in-simulator browser shell
+   - bounded simulator-side browser interaction
+   - diagnostics and browser-assisted adjunct surfaces
+
+Important boundary:
+
+- the website and protected dashboard are not superfluous
+- they own access, pricing, entitlement, notices, release posture, and pairing
+- the desktop runtime remains the actual simulator authority
+
+## First session
+
+1. Start on the public website
+   - review `/launch-status` if release posture matters
+   - review `/pricing` if access or provisioning matters
+   - review `/download` for the current public package posture
+2. Sign in or create an account
+   - continue into `/app`
+   - use the protected browser shell for account-aware follow-through
+3. Open the protected download lane
+   - use `/app/downloads`
+   - confirm target platform, entitlement, and current package proof
+4. Pair the desktop runtime
+   - generate the desktop-link token from the protected dashboard
+   - do not reuse your password inside the desktop handoff flow
+5. Verify the first simulator lane
+   - confirm the current packaged build
+   - confirm the current runtime lane you intend to use
+   - confirm the current control boundary before assuming more than the product ships
+
+## Current desktop runtime scope
+
+The desktop runtime is the current product center for:
+
+- classic-cube execution
+- recognition-assisted reconstruction
+- replay and solve explanation
+- coaching and training-session workflows
+- training analytics and diagnostics
+- higher-dimensional runtime ownership
+
+This is the current truthful desktop-first posture. Do not collapse it into a
+generic browser simulator claim.
+
+## Control and settings truth
+
+Current shipped desktop control truth includes:
+
+- classic keyboard profile `classic-wca-keyboard/v1`
+- classic-cube pointer, orbit, zoom, and action shortcuts
+- higher-dimensional dedicated-family runtime selectors
+- viewer camera settings continuity
+- bounded immersive presets and session recall
+- native operator/training inspect surfaces that keep these facts visible
+
+Representative shipped actions include:
+
+- `LMB` clockwise
+- `RMB` counter-clockwise
+- `MMB drag` orbit
+- `wheel` zoom
+- `R` scramble
+- `H` hint
+- `Enter` submit
+- `F` mode
+- `V` hold-to-talk
+- `C` cycle voice
+
+## Higher-dimensional runtime truth
+
+Current higher-dimensional truth includes:
+
+- dedicated `Magic120Cell` runtime/profile ownership
+- dedicated `MagicCube5D` runtime/profile ownership
+- first-party session, scene, projection, and persistence ownership
+- generated-mode selector recall through native operator and training surfaces
+- packaged proof on the maintained Windows Unreal validation lane
+
+The serious higher-dimensional lanes are not placeholders in the live product
+story. They remain part of current product truth.
+
+## XR and controller truth
+
+HyperTwist does not currently claim a finished VR/controller product lane.
+
+Current truthful boundary:
+
+- desktop-hosted native OpenXR/controller widening is `No-Go`
+- the project does not currently market a finished headset/runtime lane
+- controller rebinding and broader user-facing XR preferences are not yet shipped
+- any future reopen must prove:
+  - dedicated runtime ownership
+  - user-facing settings and controller-rebinding ownership
+  - Windows packaged controller validation with real controller truth
+
+Do not market the current input groundwork as finished VR support.
+
+## Browser and dashboard use
+
+Use the public website when you need:
+
+- public docs and onboarding
+- pricing and launch posture
+- release notes
+- notices and corresponding-source references
+- public route atlas and support guidance
+
+Use the protected dashboard when you need:
+
+- account state
+- entitlement and plan-aware download posture
+- protected launch status
+- protected notices
+- browser-to-desktop token handoff
+
+Use the desktop runtime when you need:
+
+- the actual simulator
+- packaged training behavior
+- higher-dimensional execution
+- native diagnostics or runtime-adjacent operator work
+
+## Download and release follow-through
+
+The public `/download` page describes supported targets and release posture.
+The actual delivery authority stays in the protected release lane.
+
+Check these before broader rollout:
+
+- desktop target configured
+- packaged validation proof visible
+- corresponding-source URL configured when required
+- notices reference configured
+- pricing and provisioning posture truthful
+- support contact present
+
+## Degraded-state guidance
+
+If the auth server or release manifest is degraded:
+
+- keep public posture and protected fallback guidance separate from live release authority
+- do not treat fallback continuity as proof of full production readiness
+- use the protected launch-status and support routes for the next truthful move
+
+## Support lanes
+
+Use the public or protected support path according to the problem:
+
+- launch readiness
+  - checkout wiring
+  - release target publication
+  - notice and corresponding-source follow-through
+- operator access
+  - sign-in
+  - entitlement
+  - protected download access
+  - pairing
+- studio rollout
+  - broader deployment planning
+  - higher-dimensional readiness review
+  - production-lane coordination
+
+Primary support contact:
+
+- `hello@hypertwist.app`
+
+## Canonical public routes
+
+- `/`
+- `/about`
+- `/features`
+- `/resources`
+- `/getting-started`
+- `/docs`
+- `/pricing`
+- `/download`
+- `/support`
+- `/changelog`
+- `/launch-status`
+- `/open-source-notices`
+- `/privacy`
+- `/terms`
+- `/shipping-payment`
+
+Primary protected routes:
+
+- `/app`
+- `/app/launch-status`
+- `/app/downloads`
+- `/app/browser-access`
+- `/app/account`
+- `/app/notices`
+
+## Final operating rule
+
+Read HyperTwist as a desktop-first simulator with a necessary browser shell
+around it.
+
+Keep both.
+
+- keep the browser for access, release, legal, and pairing work
+- keep the desktop for simulator authority
+- keep the current XR/controller boundary explicit
--- a/website/src/tests/public-marketing-pages.test.tsx
+++ b/website/src/tests/public-marketing-pages.test.tsx
@ -286,6 +286,8 @@ describe('public marketing pages', () => {
    expect(within(downloadDecisionGuideSection as HTMLElement).getByText('Need the protected desktop-download lane?')).toBeTruthy()
    expect(within(downloadDecisionGuideSection as HTMLElement).getByText('Need notices, corresponding source, or release follow-through?')).toBeTruthy()
    expect(screen.getByText('First launch and desktop setup')).toBeTruthy()
+    expect(screen.getByText('Offline operator manual')).toBeTruthy()
+    expect(screen.getByRole('link', { name: 'Download offline operator manual' }).getAttribute('href')).toBe('/manual/hypertwist-operator-manual.md')
    expect(screen.getByText('First desktop session after install')).toBeTruthy()
    expect(screen.getByText('2. Pair the installed runtime without password reuse')).toBeTruthy()
    expect(screen.getByText('Digital delivery workflow')).toBeTruthy()
@ -484,6 +486,8 @@ describe('public marketing pages', () => {
    expect(screen.getByText('What the first serious session should look like')).toBeTruthy()
    expect(screen.getByText('1. Resolve access and choose the right build')).toBeTruthy()
    expect(screen.getByText('Which public page should you open next?')).toBeTruthy()
+    expect(screen.getByText('Offline operator manual')).toBeTruthy()
+    expect(screen.getByRole('link', { name: 'Download offline operator manual' }).getAttribute('href')).toBe('/manual/hypertwist-operator-manual.md')
    expect(screen.getByText('Launch status')).toBeTruthy()
    expect(screen.getByText('Choose the right HyperTwist surface')).toBeTruthy()
    expect(screen.getByText('Move into the protected dashboard')).toBeTruthy()
@ -1185,6 +1189,8 @@ describe('public marketing pages', () => {
    expect(screen.getByText('Higher-dimensional runtime ownership')).toBeTruthy()
    expect(screen.getByText('Public manual route atlas')).toBeTruthy()
    expect(screen.getByText('Shipping & payment')).toBeTruthy()
+    expect(screen.getByText('Offline operator manual')).toBeTruthy()
+    expect(screen.getByRole('link', { name: 'Download offline operator manual' }).getAttribute('href')).toBe('/manual/hypertwist-operator-manual.md')
    expect(screen.getByText('Choose the next release move')).toBeTruthy()
    expect(screen.getByText('Need account state, pairing, or protected browser follow-through?')).toBeTruthy()
    expect(screen.getByText(/The web lane is not superfluous/i)).toBeTruthy()
@ -1325,6 +1331,8 @@ describe('public marketing pages', () => {
    expect(screen.getByText('Operator manual')).toBeTruthy()
    expect(screen.getByText('First real desktop session')).toBeTruthy()
    expect(screen.getByText('Recovery and degraded-state manual')).toBeTruthy()
+    expect(screen.getByText('Offline operator manual')).toBeTruthy()
+    expect(screen.getByRole('link', { name: 'Download offline operator manual' }).getAttribute('href')).toBe('/manual/hypertwist-operator-manual.md')
    expect(screen.getByText('Support topic quick routes')).toBeTruthy()
    expect(screen.getAllByText('Current surface authority map').length).toBeGreaterThan(0)
    expect(screen.getByText('Why HyperTwist keeps both a website and a desktop runtime')).toBeTruthy()
@ -1463,6 +1471,8 @@ describe('public marketing pages', () => {

    expect(screen.getByText('The first serious HyperTwist session')).toBeTruthy()
    expect(screen.getByText('Operator path')).toBeTruthy()
+    expect(screen.getByText('Offline operator manual')).toBeTruthy()
+    expect(screen.getByRole('link', { name: 'Download offline operator manual' }).getAttribute('href')).toBe('/manual/hypertwist-operator-manual.md')
    expect(screen.getByText('Browser account access methods')).toBeTruthy()
    expect(screen.getByText('First launch and desktop setup')).toBeTruthy()
    expect(screen.getByText('Simulator use today')).toBeTruthy()
--- a/website/src/pages/public-page-helpers.tsx
+++ b/website/src/pages/public-page-helpers.tsx
@ -128,6 +128,8 @@ export const releaseCommerceFallback = {
  planPriceStudio: studioFallbackPlan.price,
 }

+export const downloadablePublicManualHref = '/manual/hypertwist-operator-manual.md'
+
 export function buildPublicReleaseManifestFallback(supportEmail = brandConfig.contact.email) {
  return {
    downloadTargets,
@ -378,6 +380,42 @@ export function OperatorDesktopQuickstartSection({
  )
 }

+export function DownloadableOperatorManualSection({
+  title = 'Offline operator manual',
+  description = 'HyperTwist now ships a same-origin downloadable operator manual so the desktop-first onboarding, control-boundary truth, and rollout guidance can travel with the product instead of living only in live browser routes.',
+}: {
+  title?: string
+  description?: string
+}) {
+  return (
+    <Section title={title} description={description}>
+      <article className="card">
+        <p>
+          The downloadable manual bundles the current first-session path, browser-versus-desktop
+          boundary, protected dashboard follow-through, control roster, higher-dimensional runtime
+          guide, and the current XR/controller truth into one offline reference.
+        </p>
+        <ul className="list top-gap">
+          <li>Use it for desktop-side onboarding, rollout review, and operator support when the browser shell is not the best reading surface.</li>
+          <li>It stays aligned with the current public route atlas instead of inventing a separate product story.</li>
+          <li>It keeps the current desktop-hosted XR/controller `No-Go` boundary explicit instead of flattening it into generic VR support language.</li>
+        </ul>
+        <div className="button-row top-gap">
+          <a className="button button--primary" href={downloadablePublicManualHref} download>
+            Download offline operator manual
+          </a>
+          <Link className="button button--ghost" to="/docs">
+            Open public manual
+          </Link>
+          <Link className="button button--ghost" to="/getting-started">
+            Open getting started
+          </Link>
+        </div>
+      </article>
+    </Section>
+  )
+}
+
 export function PrincipleCardSection({
  title,
  description,
@ -728,6 +766,16 @@ export function PublicPackagedDesktopProofSection({
  )
 }

+type ReleaseAuthorityReference = {
+  title: string
+  description: string
+  href: string | null
+  configuredLabel: string
+  missingLabel: string
+  linkLabel: string
+  download?: boolean
+}
+
 export function ReleaseAuthorityBundleSection({
  releaseManifest,
  title = 'Release references and source availability',
@ -737,7 +785,17 @@ export function ReleaseAuthorityBundleSection({
  title?: string
  description?: string
 }) {
-  const references = [
+  const references: readonly ReleaseAuthorityReference[] = [
+    {
+      title: 'Downloadable operator manual',
+      description:
+        'A same-origin offline manual ships with the website so desktop-first onboarding, protected-release follow-through, and rollout review do not depend on live browsing alone.',
+      href: downloadablePublicManualHref,
+      configuredLabel: 'Included',
+      missingLabel: 'Include the downloadable operator manual before external launch',
+      linkLabel: 'Download operator manual (.md)',
+      download: true,
+    },
    {
      title: 'Public manual',
      description:
@ -801,9 +859,15 @@ export function ReleaseAuthorityBundleSection({
              <p>{reference.description}</p>
              <p className="top-gap">
                {reference.href ? (
-                  <a href={reference.href} target="_blank" rel="noreferrer">
-                    {reference.linkLabel}
-                  </a>
+                  reference.download ? (
+                    <a href={reference.href} download>
+                      {reference.linkLabel}
+                    </a>
+                  ) : (
+                    <a href={reference.href} target="_blank" rel="noreferrer">
+                      {reference.linkLabel}
+                    </a>
+                  )
                ) : (
                  reference.missingLabel
                )}
--- a/website/src/pages/public-pages-commerce.tsx
+++ b/website/src/pages/public-pages-commerce.tsx
@ -30,6 +30,7 @@ import {
  BrowserAuthMethodsSection,
  BrowserDesktopRealitySection,
  DeliverySurfaceResponsibilitiesGrid,
+  DownloadableOperatorManualSection,
  explorerFallbackPlan,
  HigherDimensionalRuntimeGuideSection,
  OperatorDesktopQuickstartSection,
@ -323,6 +324,10 @@ export function DownloadPage() {
          cards={desktopFirstLaunchCards}
        />

+        <DownloadableOperatorManualSection
+          description="The download lane now also includes a same-origin offline manual so the first-session path, current controls, higher-dimensional runtime guide, and rollout boundary can be carried alongside the desktop build."
+        />
+
        <OperatorDesktopQuickstartSection title="First desktop session after install" />

        <Section title="Release posture">
--- a/website/src/pages/public-pages-marketing.tsx
+++ b/website/src/pages/public-pages-marketing.tsx
@ -35,9 +35,10 @@ import {
  BrowserAuthMethodsSection,
  BrowserDesktopDecisionFaqSection,
  BrowserDesktopRealitySection,
+  BulletCardSection,
  ControlProfileRosterSection,
  DeliverySurfaceResponsibilitiesGrid,
-  BulletCardSection,
+  DownloadableOperatorManualSection,
  FaqCardSection,
  HigherDimensionalRuntimeGuideSection,
  InputAndDevicePostureSection,
@ -211,6 +212,10 @@ export function HomeLanding() {
          limit={8}
        />

+        <DownloadableOperatorManualSection
+          description="The homepage now also exposes a same-origin offline manual so the desktop-first product story, first-session path, and current runtime boundary can leave the browser cleanly when needed."
+        />
+
        <PublicPackagedDesktopProofSection
          platform={windowsValidationPlatform}
          actions={[
@ -503,6 +508,10 @@ export function ResourcesPage() {
          description="The resource portal is stronger when it also explains what each public page is for, so teams can move from reference reading into the exact route that owns the next question."
        />

+        <DownloadableOperatorManualSection
+          description="Resources now also expose the downloadable manual directly so rollout teams can carry one offline operator reference beside the richer live route atlas."
+        />
+
        <SurfaceChoiceGuideSection description="The resource portal is most useful when it also tells operators where to go next: stay public for references, move protected for release access, and move native for simulator execution." />

        <BrowserDesktopRealitySection />
@ -631,6 +640,10 @@ function GettingStartedPageContent({
        cards={desktopWorkflowTracks}
      />

+      <DownloadableOperatorManualSection
+        description="The onboarding route now also ships an offline manual reference so the first-session path, control truth, and browser-to-desktop split can travel with the desktop install."
+      />
+
      <BrowserAuthMethodsSection
        description="The onboarding path is easier to trust when the shared-auth provider lineup is visible before operators cross into the protected shell."
      />
@ -756,6 +769,10 @@ export function DocsPage() {
          description="The manual is easier to use when it also says which public route owns which question, so operators do not have to infer structure from navigation labels alone."
        />

+        <DownloadableOperatorManualSection
+          description="The docs lane now also provides a same-origin offline manual asset for operators who want the current route atlas, first-session flow, and runtime boundary in one downloadable reference."
+        />
+
        <BulletCardSection
          title="Current shipped capability"
          description="This section is the public manual's feature-registry-backed answer to the obvious question: what is actually live in HyperTwist today?"