# AiMe UX and Multi-Device Plan

Status: Draft product UX plan  
Last updated: 2026-08-15

Implementation status: the real Chat feasibility investment gate in
[the delivery roadmap](ROADMAP.md) recorded a scoped `GO`. Phase 2 local
onboarding work is in progress; the desktop shell, Managed mode, and complete
multi-device experience remain unimplemented and subject to their own gates.
The repository now has a local proof for signed local approval, single-use
pairing, explicit Ed25519 or P-256 device proof, a revocable algorithm-bound
certificate, fresh reconnect proof,
short-lived route leases, authenticated outbound logical device sessions, and bounded
Streamable HTTP forwarding to the existing local MCP boundary. A local
public-application router now composes OAuth metadata/JWKS, explicit
authorization, token exchange, JWT verification, protected-resource metadata,
and real Read-tool calls. Managed tools advertise their OAuth requirement on
the wire. A separate real-socket loopback proof now includes authenticated
device-wire handoff plus bounded TCP and WSS carriers, including a trusted-WSS
integration test and untrusted-peer rejection, but deployed HTTPS/WSS,
service-grade reconnect, and a deployable gateway remain separate work. This
is not a user-facing Managed service. A managed consumer gateway runtime now
owns the unbound OAuth/MCP/WSS lifecycle and issues route leases only from
verified account claims plus an exact non-secret device/profile selection; it
does not create a listener or choose the pairing UI. A separate Windows helper
now proves current-user non-exportable P-256 identity creation and signing. A
headless coordinator derives the public pairing intent from that identity,
requires an exact server-authenticated proposal and explicit local confirmation
before signing, validates the returned schema-v2 credential, and commits only
through an atomic protected-store seam. The Windows implementation now stores
that exact record in an identity-bound DPAPI CurrentUser blob with private ACL,
no-replace publication, restart recovery, and digest-guarded deletion. A
post-enrollment Windows bootstrap now reloads the record, reopens the exact CNG
identity, and starts authenticated reconnect without silently enrolling or
replacing anything. The real Managed broker, Managed confirmation screen,
durable repair outbox, registry, and Managed wizard composition are not
implemented. A separate Personal-mode setup dialog now covers only creation of
a missing fixed-state tunnel configuration from four existing user-owned
inputs; it never receives the raw runtime key and cannot replace a different
existing configuration. Account login/consent, deployed endpoints,
service-grade durable storage, public cloud routing, and the web experience remain
unimplemented.

A separate Windows-local Modify runtime now composes schema-v2 policy, native
SafeFs, Read/Modify MCP tools, JSONL/protocol audit, a pending-action broker,
and a native default-Deny confirmation dialog over an internal stdio child. A
dedicated pre-release tunnel can supervise that child and retain both native
helpers as immutable inputs. The tunnel parent now binds its exact validated
profile bytes to the supervisor-retained profile handle before the MCP child can
start. It is still not an accepted user-facing
experience: helper authenticity depends on future signed packaging, no operator
flow resolves `repair_required`, and actual Chat confirmation behavior is not
yet proven. Supported Read stdio and Managed transport continue to reject
Modify.

## Product UX decision

AiMe uses a **local-first hybrid model**:

- the signed Windows app is authoritative for roots, profiles, capabilities,
  high-risk approvals, credentials, active tasks, audit, and emergency stop;
- ChatGPT Chat is the planning and conversational surface;
- Personal local mode supports a private installation without managed sharing
  where the selected transport permits it; and
- Managed mode uses a real multi-tenant web control plane for login,
  organizations, several computers, sharing, administration, revocation, and
  update policy, but it is not the local execution/security authority.

The local app may render a modern web-based interface inside a desktop host,
provided it does not introduce an unauthenticated public or localhost control
surface. The exact UI framework remains an architecture decision.

## Why the local app is primary

Only the local app can reliably provide user presence, a native folder picker,
credential protection, foreground target confirmation, Windows process control,
emergency stop, and safe offline/recovery behavior. A remotely delivered page
must not be able to grant itself local authority merely because the user is
signed in.

## Experience surfaces

| Surface | Responsibilities | Must not do |
| --- | --- | --- |
| ChatGPT Chat | Understand the request, plan, call AiMe tools, and explain results. | Grant permissions, create roots, approve itself, or silently switch target. |
| AiMe local app | Onboard, configure devices/profiles, approve risk, show tasks, stop/revoke, protect secrets, and audit. | Hide impactful effects or depend on prompt text as authority. |
| User web app | Login/account security, organizations, owned/shared devices and profiles, connection setup, session metadata, share/revoke, and update status. | View local content, add roots, satisfy local confirmation, or send arbitrary commands. |
| Organization Admin web | Members, roles, invitations, managed inventory, share requests, tenant policy, version compliance, and tenant audit metadata. | Convert an organization role into local capability or bypass local activation. |
| Platform Admin web | Redacted service operations, suspend/revoke, security events, releases, quotas later, and support metadata. | Impersonate tool users, retrieve credentials/content, or control a device. |

## Local information model

```text
AiMe user account
`-- Organization / personal tenant
    |-- memberships, roles, and invitations
    |-- Device (one AiMe installation)
    |   |-- device identity, alias, connection, and version
    |   |-- Profile A
    |   |   |-- local roots, capabilities, and confirmation policy
    |   |   |-- recipient shares and policy versions
    |   |   `-- sessions and audit events
    |   `-- Profile B
    |       `-- independent policy, shares, and sessions
    `-- tenant policy and administrative audit
```

### Device

A device has a random independent identity, user-selected display name, local
key material, version/health state, and revoke boundary. Its remote display does
not require a Windows hostname, account name, IP address, or filesystem path.

### Profile

A profile belongs to exactly one device. It defines root aliases, capabilities,
limits, consent behavior, retention, and one transport/app binding for the first
multi-device release. Profiles do not share grants merely because they belong
to the same device.

Example:

```text
Home PC
  - Documents (Read)
  - Development (Modify)

Notebook
  - Personal (Read)
  - Presentation (Control)
```

### Session

A session is time-bounded and fixed to one device/profile pair. It contains
active operations and grants, but not a reusable broad credential. A model tool
call cannot switch the session to another device or profile.

### Account, organization, and profile share

An account authenticates one person. An organization owns membership, devices,
profiles, sharing policy, and tenant audit metadata. A profile share delegates
an explicit tool/capability ceiling to a recipient for a bounded period. The
share remains pending until the target local app activates the policy version;
an organization role alone does not grant computer access.

## Local app navigation

### Tray and quick panel

The current offline Windows slice implements only a narrow local lifecycle
surface: Starting, Personal Connect setup required, OpenAI control-plane ready (without
claiming Chat connectivity), Stopping, Failed, and Stop. It does not yet implement
the richer profile, session, task, settings, or audit navigation below, and its
installed shell behavior has not been exercised.

- connection state: Disconnected, Connecting, Connected, Degraded, Revoked;
- active device/profile and current Chat session indicator;
- active task count and pending approval count;
- capability-level indicator;
- `Stop everything` control that is always reachable during active work; and
- shortcut to full settings and audit.

### Full settings

1. **Overview** — connection, active profile, tasks, warnings, and next action.
2. **Computers** — local device identity and, later, linked-device aliases and
   presence.
3. **Profiles** — roots, capabilities, limits, confirmation policy, connection,
   duplicate, disable, and revoke.
4. **Sessions and tasks** — initiating profile, requested effect, progress,
   output summary, cancel, and final result.
5. **Approvals** — exact local effect, target, risk reason, allow once, bounded
   grant where permitted, or deny.
6. **Audit** — allow/deny metadata and reason codes without content or secrets.
7. **Connection** — tunnel setup, health, reconnect, key rotation, and revoke.
8. **Security and updates** — app version, signature/update status, privacy,
   retention, exportable diagnostics, and uninstall/recovery guidance.

## Web app navigation

### User area

1. **Home** — organizations, owned/shared profiles, active connections, alerts,
   and safe next action.
2. **Computers** — aliases, owner, presence/callable distinction, version,
   profiles, pairing, lost-device, and revoke.
3. **Shared with me** — capability ceiling, owner, expiry, connection setup,
   sessions, and self-revoke.
4. **Sharing** — grantee, explicit tools/ceiling, expiry, limits, pending local
   activation, active use, and revoke.
5. **Connections** — ChatGPT connection identity, target, status, and revoke.
6. **Account security** — passkeys/MFA, active web sessions, recovery, export,
   and deletion.

### Organization Admin area

- settings and ownership;
- members, fixed roles, invitations, and removal;
- managed computers/profiles and pending local activations;
- sharing ceilings, expiry, concurrency, version policy, and revoke;
- tenant security/audit metadata and export/delete workflows.

### Platform Admin area

- users/organizations by stable ID and redacted metadata;
- suspension and credential/connection revoke;
- aggregate device, version, tunnel, deployment, and migration health;
- release channels, staged rollout, pause/revoke, and minimum versions;
- security events and immutable administrator audit; and
- user-submitted redacted support diagnostics.

There is no platform-admin file browser, screen viewer, prompt viewer, token
viewer, arbitrary command console, or silent user impersonation.

## First-run flow

1. Install the signed AiMe package as a standard user.
2. Launch the local wizard and explain that ChatGPT will call local tools.
3. Choose Personal or Managed mode. Managed mode opens standards-based login;
   password, MFA, passkey, recovery, and OAuth consent remain user actions.
4. In Managed mode, select/create an organization and pair this device using a
   short-lived request that is explicitly confirmed in the local app.
5. Choose a device display name that need not equal the Windows hostname.
6. Create the first profile.
7. Select one or more local folders with a native folder picker and assign
   remote-safe aliases.
8. Select an initial capability level; default to Read.
9. Review exact tools, limits, confirmation behavior, and privacy implications.
10. Connect OpenAI using the supported tunnel setup while keeping the credential
   value outside the AiMe MCP process.
11. Run local, control-plane where applicable, and remote discovery checks.
12. Open a new ChatGPT Chat with the intended AiMe profile selected.
13. Perform a harmless status/list/read verification and show where to stop or
    revoke the connection.

No login password, MFA response, OAuth consent, or sensitive API key is entered
by automation on behalf of the user.

The current Personal-mode implementation covers only step 10 when the user
already has a profile, DPAPI-protected runtime-key blob, tunnel client, and
Tunnel ID. It prepares the fixed private Local App Data state and creates a
missing `tunnel.json` through the native no-replace finalizer. The other steps,
repair of a different existing configuration, installed-shell activation, and
the complete non-technical first-run journey remain acceptance work.

## Daily-use flow

1. The local tray and web app distinguish web health, policy lease, device
   presence, tunnel readiness, and actual callable state.
2. The user opens ChatGPT Chat through their own authenticated connection and
   selects the intended device/profile target.
3. ChatGPT calls tools within that fixed user/device/profile session.
4. Account role, active share/lease, and local profile policy intersect for
   every call; higher-risk actions create a local approval card.
5. A recipient cannot use a pending, expired, revoked, or locally unacknowledged
   share.
6. The local app shows progress and keeps emergency stop visible.
7. ChatGPT reports results; local and web control-plane layers record their own
   content-free audit metadata.
8. Session/lease expiry removes temporary grants and active process authority.

## Approval UX

An approval card displays:

- device and profile aliases;
- initiating session and tool;
- exact target/effect, using local paths only in the local UI;
- why the action exceeds the current standing grant;
- whether it is reversible and how rollback works;
- `Deny` and `Allow once` as the safe defaults; and
- a bounded-session option only where the capability model permits it.

ChatGPT-provided rationale may be shown as untrusted context, but never replaces
the locally derived effect summary. Control and Full grants retain a persistent
foreground indicator until they expire or are stopped.

## Multiple-computer flow

### Managed multi-device design

1. Sign in to the same account/organization and install AiMe separately on the
   second computer.
2. Create and locally confirm a new device identity, ownership binding, and
   display alias.
3. Create local profiles and roots on that computer.
4. Publish only aliases/capability metadata required for management and bind a
   distinct authenticated connection for each exposed profile/recipient where
   necessary.
5. User and web UIs show the intended owner and target; ChatGPT may initially
   present explicit entries such as:
   - `AiMe - Home PC - Development`
   - `AiMe - Notebook - Personal`
6. The user selects the target before starting the conversation; a live session
   cannot silently retarget.

Separate connections remain the safe initial data-plane model because they make
the user/profile binding explicit. Duplicate display names receive a warning,
but stable identities remain unambiguous.

### Sharing with another person

1. The owner chooses one profile and a recipient, explicit tools/capability
   ceiling, expiry, and limits in the web app.
2. The share appears as pending on the intended local computer.
3. The local owner verifies the recipient/effect and activates or denies it.
4. The recipient accepts the invitation, secures their account, and creates
   their own authenticated ChatGPT connection.
5. Active use shows recipient/session metadata locally and in the authorized web
   view; content remains local/ChatGPT data-plane only.
6. Owner, recipient, Organization Admin where policy permits, or Platform
   Security Admin for suspension can revoke. The next call fails closed.

### Optional unified Chat target selection

A future Chat app may expose computer/profile selection through the managed
control plane only after it proves authenticated caller/connection identity,
tenant and route isolation, explicit target binding, replay protection,
presence accuracy, and revoke. This is a data-plane routing decision, not a
reason to give the web dashboard arbitrary device-command authority.

## Switching, offline, revoke, and uninstall

- Switching device/profile starts a new session. Existing work is cancelled or
  explicitly completed; it is never silently retargeted.
- Offline state distinguishes user-stopped, network unavailable, credential
  revoked, update required, and unknown/stale presence where evidence permits.
- Revoking one device/profile must not revoke or widen another.
- Lost-device flow revokes the remote binding without requiring access to that
  computer.
- Control-plane outage or expired managed lease stops new remote tool actions
  after the documented grace window; local emergency stop, local revoke, and
  uninstall remain usable.
- Local uninstall stops the supervised tree, revokes or guides revocation of the
  binding, removes protected secrets and runtime state, and offers explicit
  audit retention/removal choices.

## Accessibility and clarity requirements

- Full keyboard navigation and screen-reader labels for setup, approval, stop,
  revoke, and recovery flows.
- Color is not the only status or risk indicator.
- Thai and English UI text must preserve the same capability meaning; security
  terms are not softened during localization.
- High-risk controls use clear verbs and concrete effects rather than generic
  `Allow` or `Continue` where ambiguity would matter.
- The emergency stop path remains usable when a child application has focus.

## UX acceptance scenarios

1. A new user installs, creates a Read profile, connects, and completes a Chat
   read test without a terminal.
2. The same user creates a Modify profile without widening the Read profile.
3. A hostile file or webpage causes a higher-risk request; the local card shows
   the real effect and denial leaves no partial action.
4. The user stops an active process/UI-control task and no descendant or input
   automation remains.
5. A second computer is paired through the managed web app, used independently,
   then revoked without affecting the first.
6. An owner shares a Read profile with another authenticated person; use is
   blocked before local activation and after expiry/revoke.
7. User, Organization Admin, and Platform Admin pages enforce their role and
   content boundaries under cross-tenant negative tests.
8. A lost or offline device is distinguishable enough for the user to choose a
   safe recovery action.
9. Local app, ChatGPT, and web views never disagree in a way that
   silently routes a command to a different device/profile.
10. A signed staged update completes without interrupting active work; corrupt,
    downgraded, unsigned, or unhealthy versions fail or recover safely.

## Open UX decisions

- Desktop framework and secure in-process IPC mechanism.
- Human identity provider, recovery, and account-deletion implementation.
- Whether one authenticated profile/recipient connection remains acceptable at
  scale or a unified selector can prove equivalent identity/isolation.
- What authenticated session identity, if any, OpenAI forwards to the local MCP
  process and how much the UI can truthfully display.
- Exact approval batching and expiry defaults for Modify, Control, and Full.
- Managed policy-lease/offline grace duration and whether a locally pre-approved
  bounded Read delegation rule is worth supporting.
- Exact Windows package/updater UX and organization version-deferral policy.

The complete web role/sharing model is defined in the
[web control-plane and RBAC plan](WEB_CONTROL_PLANE_AND_RBAC_PLAN.md). Hosting
and client-update UX constraints are defined in the
[deployment and automatic update plan](DEPLOYMENT_AND_UPDATE_PLAN.md).
