# HyperTwist Operator Manual

Last updated: 2026-07-01

## 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, settings, and desktop workflow truth
- higher-dimensional runtime ownership
- release, billing, and distribution posture
- support, recovery, and escalation guidance
- 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

## Why the website stays and where it is intentionally weaker

### What the website is for

- public docs, route atlas, and product-safe onboarding
- pricing, launch posture, release notes, and notices
- support-safe rollout guidance
- protected account state, entitlement, and browser-to-desktop pairing

### What the desktop runtime is for

- package-validated simulator execution
- recognition, replay, coaching, analytics, and training continuity
- higher-dimensional packaged execution
- native diagnostics and runtime-adjacent operator work

### What the browser does not claim

- package-validated training behavior
- higher-dimensional packaged execution authority
- low-latency native device/runtime integration authority
- finished XR/controller runtime ownership

That narrower browser boundary is intentional. It keeps access, release,
billing, pairing, and legal-distribution work inspectable outside the simulator
while keeping the real training runtime easier to trust.

### What you do not get if you stay browser-only

If you stay only on the website, you do not get the main simulator value:

- the real classic-cube practice loop
- recognition, correction closure, and solve-guidance execution
- replay, coaching, analytics, and local leaderboard continuity
- dedicated `Magic120Cell` or `MagicCube5D` packaged-family runtime execution
- the native diagnostics that prove higher-dimensional session, scene,
  persistence-boundary, and state-semantics ownership

In short:

- the browser version is useful, but it is intentionally weaker than the
  downloadable for actual training and serious study
- the downloadable remains the primary product because it is where the current
  simulator authority really lives

### What the browser version is still excellent for

- public docs, help-center, and route-atlas reading
- pricing, launch-status, and release-note review
- account access and protected entitlement posture
- protected notices and corresponding-source follow-through
- browser-to-desktop pairing and rollout-safe support coordination

## Browser access and account posture

The browser lane is intentionally narrower than the simulator.

Use it for:

- public documentation and rollout context
- account access and protected release posture
- pricing and entitlement follow-through
- release notes, notices, and corresponding-source references
- browser-to-desktop identity pairing

Current truthful browser auth posture:

- email/password is the baseline shared-auth lane
- GitHub, Google, and ORCID may also appear when the deployment has them configured
- sign-in opens protected account, release, and pairing surfaces
- sign-in does not turn the browser into the simulator

## First operator journey

Use this as the current first serious-session path.

### 1. Resolve access and choose the right build

- start on `/download` when the target platform matters
- review `/launch-status` when rollout posture matters
- review `/pricing` when access, plan, or provisioning matters
- preserve the chosen platform through sign-in into the protected release lane

### 2. Sign in and move into the protected shell

- continue into `/app`
- use the protected browser shell for account-aware follow-through
- keep release posture, notices, and entitlement attached to the same account context

### 3. Open the protected download lane

- use `/app/downloads`
- confirm target platform, entitlement, and current package proof
- treat the protected release lane as the delivery authority

### 4. Pair the installed desktop runtime

- generate the desktop-link token from the protected dashboard
- use the token during first launch
- do not reuse your password inside the desktop handoff flow

### 5. Verify the first native session

- confirm the current packaged build and release notes
- open the first classic-cube training lane
- verify the shipped control roster before assuming broader device support
- verify the higher-dimensional lane you intend to use
- keep the XR/controller boundary explicit

## First-session verification checklist

### Verify the delivered build and release context

- confirm the platform, channel, version/build id, and packaged-validation
  summary on the public or protected download surface
- review release notes, notices, and corresponding-source posture before wider
  rollout or redistribution
- keep the protected release lane as the delivery authority instead of relying
  on remembered package assumptions

### Verify the shipped control roster and current boundary

- confirm the shipped classic profile `classic-wca-keyboard/v1` together with
  pointer, orbit, zoom, hint, and hold-to-talk behavior
- read camera-export continuity, immersive recall, and higher-dimensional
  selector posture as current bounded settings truth rather than a finished
  global rebinding suite
- keep the desktop-hosted `No-Go` on native OpenXR/controller widening explicit
  instead of treating groundwork as finished VR or controller support

### Verify the classic training lane

- launch the classic-cube lane and confirm timer, scramble, HUD, replay,
  coaching, and diagnostics posture
- treat recognition, reconstruction, and solve-guidance behavior as native
  runtime authority
- return to the browser shell only when account, release, entitlement, or
  support posture becomes the next actual job

### Verify the higher-dimensional lane you plan to use

- launch the dedicated `Magic120Cell` or `MagicCube5D` packaged map from the
  desktop runtime
- confirm the selector, projection, focus, symmetry/stereo, and visibility
  posture you intend to use
- use native diagnostics when session, interactive-scene, persistence-boundary,
  or state-semantics ownership needs confirmation

## Current desktop workflow tracks

### Classic-cube practice

Use the desktop runtime when the goal is actual practice rather than product
orientation.

- launch the classic-cube training lane from the installed desktop runtime
- confirm the timer, scramble, HUD, and replay posture first
- use the native desktop lane as the authoritative practice loop rather than a browser substitute

### Recognition and correction

Use the desktop runtime when you need the real cube-state intake and
reconstruction workflow.

- calibrate and observe the cube through the bounded recognition lane
- use browser-assisted recognition and native correction closure together
- read reconstruction and solve guidance as desktop workflow truth

### Replay, coaching, and analytics

Use the desktop runtime when the session needs review continuity.

- finish or import the training session
- review replay, coaching, leaderboard, and diagnostics surfaces in the native runtime
- return to the browser shell only when account, release, entitlement, or support posture becomes the next concern

### Higher-dimensional sessions

Use the packaged dedicated-family maps when training moves beyond the classic
cube.

- launch the dedicated `Magic120Cell` or `MagicCube5D` map from the desktop runtime
- use the shipped selector, focus, projection, symmetry/stereo, and visibility posture
- use selector recall when the latest persisted generated-mode launch request is valid
- keep XR/controller widening explicit No-Go rather than assuming parity from groundwork alone

### Browser-return governance

Return to the browser shell when the job becomes commercial, operational, or
release-facing rather than simulator-facing.

- use the protected dashboard for plan, entitlement, desktop-link pairing, and release-manifest review
- use public or protected launch-status, notices, pricing, and release-notes routes when rollout posture changes
- keep browser access issues separate from native runtime issues

## 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.

## Current puzzle and workflow lineup

These are the main study lanes the downloadable already owns today:

- classic-cube practice and timing
- recognition, reconstruction, and solve guidance
- replay, coaching, analytics, and operator diagnostics
- `Magic120Cell` packaged runtime
- `MagicCube5D` packaged runtime
- `MagicTile` embedded-browser runtime posture inside Unreal

The website can explain every one of these. The website does not execute them.

## 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

Representative shipped keyboard roster includes:

- `I/K = R/R'`
- `J/F = U/U'`
- `H/G = F/F'`
- `D/E = L/L'`
- `S/L = D/D'`
- `W/O = B/B'`
- `T/Y = x/x'`
- `N/B = y/y'`
- `P/Q = z/z'`

Current settings truth also includes:

- viewer camera settings ownership
- bounded camera-export continuity through `artifact/camera-export-json`
- immersive session-local recall through `immersive-training-session-recall-boundary`
- dedicated family-specific view defaults for `Magic120Cell` and `MagicCube5D`
- native diagnostics that expose the active activation, view-context, session, and interactive-scene owners

This is real settings ownership, but it is still narrower than a finished
global rebinding/preferences suite.

## 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.

### Magic120Cell packaged runtime

- launch the dedicated `Magic120Cell` training map from the desktop runtime
- use the current symmetry, focus, logical-visibility depth, and center-cell posture as the owned runtime lane
- use native diagnostics to confirm the dedicated session surface, interactive-scene surface, persistence boundary, and state semantics for this family

### MagicCube5D packaged runtime

- launch the dedicated `MagicCube5D` training map from the desktop runtime
- use the current projection-distance, stereo, face-visibility, and focus posture as the owned runtime lane
- use native diagnostics to confirm the dedicated session surface, interactive-scene surface, persistence boundary, and state semantics for this family

### MagicTile embedded-browser runtime

- treat the embedded browser/CEF shell as the current shipped host for the live non-Euclidean tiling lane
- keep the first-party bridge, state transport, and timer continuity attached to the native shell
- do not describe a separate native renderer port as live while that renderer-widening gate remains explicit No-Go

## 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

Current public route guidance:

- `/browser` explains why the web version exists and why it stays narrower than
  the downloadable
- `/help` acts as the knowledge-base style route for onboarding, controls,
  troubleshooting, and rollout-safe product questions
- `/contact` is the direct human lane when the next best move is no longer a
  manual page

## Release, download, and distribution posture

HyperTwist is digitally delivered through browser account access and desktop
downloads.

Current operating rules:

- the public `/download` page describes supported targets and release posture
- actual delivery authority stays in the protected release lane
- Windows Unreal packaged validation is currently the strongest public package-proof lane
- package proof, release notes, pricing posture, notices, and corresponding-source follow-through belong to one release story

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

## Operator adjunct families

HyperTwist already has real adjunct operator surfaces around the simulator.

- current bounded speech/microphone/transcript, narration, and model-custody lanes are real
- provider-neutral routing, BYOK/profile custody, and usage/cost governance shells are real
- continuity, memory, notes, knowledge, and provenance-aware workflow families are real
- these are operator-grade support surfaces around the simulator, not a claim that the website itself becomes the training runtime

## Degraded-state and recovery guidance

### Browser auth degraded or mixed

- use degraded browser posture for bounded continuity, not as a silent claim of full production authority
- use the protected dashboard to inspect what still works and what remains intentionally withheld
- clear missing auth env vars and origin/runtime warnings before treating browser auth as fully production-ready

### Release authority temporarily unavailable

- keep fallback release context separate from real raw package-delivery authority
- use package proof, notices, and release references for orientation while live manifest authority is degraded
- refresh the protected release lane first, then escalate if rollout or entitlement work remains blocked

### Desktop-first continuity during recovery

- keep public posture and protected fallback guidance separate from live release authority
- do not treat fallback continuity as proof of full production readiness or full public-launch readiness
- use the protected launch-status and support routes for the next truthful move

## Issue reporting checklist

### Account, pairing, or entitlement issue report

- include whether the failure happened on a public route or a protected route
  and name the exact path such as `/login`, `/app`, or `/app/downloads`
- state the sign-in method and whether the UI showed normal, mixed, or fallback
  auth posture when the problem occurred
- call out whether the problem is sign-in, plan visibility, desktop-link
  pairing, or protected release access

### Download, install, or release issue report

- include platform, channel, version/build id, and the packaged-validation
  summary line
- state whether the issue is archive delivery, install, first launch,
  release-note mismatch, or notices/corresponding-source follow-through
- note whether missing raw download URLs were expected public gating or an
  actual failure inside the protected release lane

### Runtime or training issue report

- state whether the issue affects classic-cube training, recognition, replay or
  coaching, `Magic120Cell`, `MagicCube5D`, or the `MagicTile` browser-host lane
- include the current control profile or settings lane when relevant,
  especially for camera continuity, selector recall, or higher-dimensional view
  posture
- separate a real shipped regression from the explicit unfinished
  XR/controller/preferences boundary

### Rollout, pricing, or compliance issue report

- include the route, checkout/source/notices target, and whether the problem is
  launch posture, billing/provisioning configuration, or legal-distribution
  follow-through
- keep pricing, notices, corresponding-source, and release-reference issues
  distinct from simulator bugs even when found during the same operator session
- attach launch-status or release-note context when it materially explains why
  the public or protected shell could not complete the expected next move

## Support and escalation lanes

### Account and entitlement issues

- missing plan access, absent download buttons, or failed desktop-link pairing belong to the protected dashboard lane
- confirm auth, billing, and entitlement posture before troubleshooting simulator behavior

### Download and install issues

- confirm the selected platform, release version, and package validation summary first
- recheck notices, release notes, and rollout instructions before redistributing the build
- escalate with the exact target platform and release channel when the package itself is the issue

### Runtime and training issues

- call out whether the issue affects classic-cube training, replay/coaching, or higher-dimensional family maps
- separate unfinished XR/controller/preferences expectations from actual regressions in the shipped keyboard/mouse lanes
- keep MagicTile browser-host behavior and dedicated-family packaged-map behavior distinguished when reporting issues

### Rollout and compliance issues

- route pricing, notices, and corresponding-source questions through the public/support lane
- keep package, pricing, and legal posture tied together before broader operator rollout

## Canonical route atlas

### Public routes

- `/`
  - shortest truthful overview of the product, surface split, and release posture
- `/about`
  - product rationale and higher-dimensional seriousness in operator-grade language
- `/features`
  - capability truth rather than pitch language
- `/resources`
  - public reference portal for rollout, simulator, and training surfaces
- `/getting-started`
  - canonical first-session manual from browser access into the native runtime
- `/launch-status`
  - canonical public rollout and blocker authority page
- `/docs`
  - the richest public product-safe manual surface
- `/support`
  - recovery and escalation lane selection
- `/pricing`
  - plan comparison with topology and launch posture kept honest
- `/download`
  - supported targets, package proof, and protected-delivery handoff
- `/changelog`
  - operator-facing shipping chronology
- `/open-source-notices`
  - legal-distribution and corresponding-source follow-through
- `/privacy`
  - browser-account and desktop-runtime boundary wording
- `/terms`
  - access model and protected-download boundary
- `/shipping-payment`
  - digital-delivery and payment posture

### Protected routes

- `/app`
  - signed-in overview, account posture, and next operator move
- `/app/launch-status`
  - signed-in rollout authority and release follow-through
- `/app/downloads`
  - protected release lane and entitled desktop delivery
- `/app/browser-access`
  - protected browser-shell posture and boundary explanation
- `/app/account`
  - signed-in plan, session, and auth-method continuity
- `/app/notices`
  - protected distribution references and compliance follow-through

Primary support contact:

- `hello@hypertwist.app`

## 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
