# QNE Invite Trial Browser Shadow Doctrine V1

Status: current operational doctrine
Date: 2026-06-08
Layer: Layer B current support doctrine under the main node shadow doctrine
Workspace anchor: qne-node-v00505 and future browser/mobile adapter work

This doctrine extends `QNE_Main_Node_Shadow_System_Doctrine_V1.md`. It defines
how a Home Node can invite another person to try QuicknEasy before they install
their own Home Node.

## Summary

A Home Node can host a temporary invited user. The invitee accesses that user
system through a browser shadow, and may also add a mobile shadow during the
trial. The invitee's activities are recorded in the invitee user persist under
the inviter's Home Node. When the invitee installs their own Home Node, the
invitee user persist can be migrated to the invitee's new Home Node.

The invite system is not just a download link. It is a working hosted QNE trial
with a PA conversation surface that guides the invitee, explains the system, and
later assists migration.

## Invite Flow

The Home Node owner selects Invite from the Home Node UI or from an approved
shadowed mobile. The Home Node creates:

- an invite record
- an invited user UUID
- a hosted user runtime under `QNE/users/<invitee-user-uuid>`
- a browser shadow for the first remote session
- optional policy allowing the invitee to add a mobile shadow during trial
- an invite link and PIN
- optional QR code for accepting the invite

The invite message may be shared by email, native share sheet, copied link, QR
display, or other user-controlled channel.

The invite message should include:

- qne.info download link for users who want to install immediately
- browser trial link for users who want to try first
- PIN or short code
- expiry statement
- plain language instruction to open the link and enter the PIN

## Browser Trial

The invitee can open the trial link in a browser. The browser loads a reviewed
QNE browser adapter. The browser adapter does not run QNENodeSkills. It renders
QNESceneData from the Home Node and returns user actions.

The browser shadow persists browser/session-specific state only:

- invite ID
- browser session ID
- PIN verification state
- scene delivery state
- client capability hints
- expiry and revocation state
- audit events for access attempts

The browser shadow is not the user system. The invitee's actual activity belongs
in the invitee user persist.

The browser shadow follows the QNE color doctrine from the main node shadow
doctrine. Browser adapter fallback colors and shadow-rendered frame colors must
be defined from OKLCH design values and converted to CSS or Skia output formats
only at the adapter edge. The standard Personal Assistant window title bar is
pastel green.

## Invitee User Persist

The invited user's hosted state lives under the inviter Home Node:

```text
QNE/users/<invitee-user-uuid>/
  persist/
    lmdb/
    ltr/
    secrets/
  status/
    config/
    runtime/
    index/
  tmp/
  ui/
```

Invitee documents, preferences, PA state, trial activity, QNENodeSkill state,
and migration markers belong in this user persist. This layout is intentionally
portable so it can later be copied or transferred to the invitee's own Home
Node.

## Invitee Mobile Shadow

An invitee may add a mobile device during the hosted trial. That mobile shadow
is hosted by the inviter's Home Node but is bound to the invitee's hosted user,
not to the inviter's owner user.

The mobile shadow record must include enough policy context to prevent confusion:

```text
device_uuid
observed_noise_static_public_key
adapter
shadow_owner_kind = hosted_trial_user
hosted_user_uuid = <invitee-user-uuid>
invite_id = <invite-id>
approved_by = invite_policy_or_home_node_owner
trial_expires_at
revocation_state
```

The invitee mobile shadow can access only the invitee's hosted user context. It
must not gain access to the inviter's owner user/session. Trial expiry disables
both browser and mobile shadows unless the Home Node owner extends or converts
the trial.

When the invitee migrates to their own Home Node, the mobile device should be
paired to the new Home Node. The old hosted mobile shadow should be revoked,
archived, or marked migrated.

## PA-Guided Trial And Migration

Once an invitee is connected through a browser shadow, mobile shadow, local node,
or remote node, the invitee's PA is the continuity and guidance surface.

The PA should guide:

- welcome and orientation
- what the inviter has shared
- privacy and hosting boundaries
- trial expiry
- adding a mobile device
- installing the invitee's own Home Node
- migration from hosted trial to owned Home Node
- known peer/contact setup
- later membership or payment flows where applicable

Migration is a PA-led workflow, not an admin procedure. The PA can detect browser
platform hints and recommend the correct qne.info installer URL, while always
allowing the user to choose another platform.

## Platform Hint Doctrine

Browser platform detection is allowed only as a convenience hint. It may be used
to recommend an installer URL:

```text
Windows -> qne.info Windows installer
macOS -> qne.info macOS installer
Linux -> qne.info Linux installer
Android -> Play Store or Android package path
iOS -> App Store
```

Platform hints must not be used for authorization. They may be derived from user
agent data, browser feature detection, screen/touch hints, and explicit user
choice.

The canonical installer URL mapping should live on the Home Node or qne.info,
not hardcoded permanently in the browser adapter.

## Security Boundaries

An invite link and PIN do not grant broad access. They grant a controlled path
to activate the hosted trial user session.

Invite records should support:

- pending
- accepted
- expired
- revoked
- migrated

Invite links should be short-lived or policy-limited. PIN attempts should be
rate-limited. Browser and mobile shadows must be scoped to the invitee user and
invite policy.

The invitee's future Home Node owns its own node UUID and QNE P2P static key.
Migration updates the user's current Home Node relationship rather than making
the inviter's Home Node permanent.

## QR And Share Doctrine

Invite QR codes are bootstrap artifacts. They may be displayed on the Home Node
UI, displayed on an approved shadowed mobile, embedded in an email, or shared
through a native share sheet.

The QR payload for an invite should be separate from Home Node mobile pairing
payloads. A QNE invite QR identifies the invite endpoint, invite ID/nonce,
network, expiry, and optional qne.info download link. It does not authorize the
scanner to access private content by itself.

Native share sheets are preferred on mobile because they let the user choose
Mail, Messages, WhatsApp, Signal, AirDrop, or another installed channel without
QNE needing email-provider credentials.

## Migration Doctrine

When the invitee installs their own Home Node:

1. The new Home Node creates its own node UUID and static QNE P2P key.
2. The hosted invitee PA confirms the migration intent.
3. The inviter Home Node authorizes export of the invitee user persist.
4. The user persist bundle is transferred to the invitee Home Node.
5. The invitee Home Node imports it under the same invitee user UUID.
6. Public user/DHT records are updated to point to the new Home Node where
   appropriate.
7. The inviter Home Node marks the hosted user and shadows as migrated,
   read-only, revoked, or archived according to policy.

The browser/mobile trial path exists to let a person experience QNE before they
commit to running their own Home Node.
