Simplify setup journeys with guided phone pairing and bot creation

.papercuts/troubleshooting.md

@@ -311,3 +311,6 @@ owns; reopen the terminal before judging the final live state.
   platform-independent test that exercises both certificate and keychain paths.
 - A changelog search conflated the stable and prerelease lines. Verify published
   package code before assuming a release contains the upstream patch.
+
+- UX review (2026-09-05): the active Xcode installation rejects tools until its license is accepted. Git and desktop C helpers can use the separately installed Command Line Tools via `DEVELOPER_DIR=/Library/Developer/CommandLineTools`; helper build scripts replace the child environment, so this run compiled their unchanged C sources with the same flags directly. iOS physical-device discovery/test remains blocked; do not claim it passed.
+- Electron E2E failure diagnostics called `app.process()` outside their try/catch; a closed Electron target hid the original launch error. Keep that call within the best-effort diagnostic block. The isolated E2E profile also cannot establish native Bot Keychain authority; the editor test injects a test-owned IPC catalog and captures the submitted access, while storage/authority tests run separately.

android/app/src/main/java/sbtbiswas/AidenOnTheGo/features/remote/AidenPairingScreen.kt

@@ -183,14 +183,21 @@ fun AidenPairingScreen(
 
             // Pair New Mac Section
             Text(
-                text = "Pair New Mac",
+                text = "Connect your Mac",
                 style = MaterialTheme.typography.titleSmall,
                 fontWeight = FontWeight.Bold,
                 color = palette.secondary
             )
             Spacer(modifier = Modifier.height(8.dp))
 
-            // M3 Expressive 3-Tab Pill Segmented Group
+            Text(
+                text = "On your Mac, open Settings → Aiden On The Go → Connect a device. Then scan its code here.",
+                style = MaterialTheme.typography.bodyMedium,
+                color = palette.secondary
+            )
+            Spacer(modifier = Modifier.height(12.dp))
+
+            // QR first, with a camera-free setup code fallback.
             Surface(
                 color = palette.raised,
                 shape = RoundedCornerShape(20.dp),
@@ -241,31 +248,16 @@ fun AidenPairingScreen(
                         }
                     }
 
-                    // Tab 2: Paste JSON
-                    Surface(
-                        color = if (selectedTab == 2) palette.accent else Color.Transparent,
-                        shape = RoundedCornerShape(16.dp),
-                        modifier = Modifier
-                            .weight(1f)
-                            .tactilePress { selectedTab = 2 }
-                    ) {
-                        Box(
-                            contentAlignment = Alignment.Center,
-                            modifier = Modifier.padding(vertical = 8.dp)
-                        ) {
-                            Text(
-                                text = "Paste JSON",
-                                style = MaterialTheme.typography.labelMedium,
-                                fontWeight = FontWeight.Bold,
-                                color = if (selectedTab == 2) Color.White else palette.secondary
-                            )
-                        }
-                    }
+
                 }
             }
 
             Spacer(modifier = Modifier.height(16.dp))
 
+            TextButton(onClick = { selectedTab = if (selectedTab == 2) 0 else 2 }) {
+                Text(if (selectedTab == 2) "Back to scanning" else "Advanced: paste connection details")
+            }
+
             errorMessage?.let { msg ->
                 Surface(
                     color = palette.danger.copy(alpha = 0.12f),
@@ -325,7 +317,7 @@ fun AidenPairingScreen(
                         colors = sbtbiswas.AidenOnTheGo.ui.theme.aidenTextFieldColors(),
                         value = endpointUrl,
                         onValueChange = { endpointUrl = it },
-                        label = { Text("Mac Address (HTTPS Endpoint)") },
+                        label = { Text("Mac address") },
                         singleLine = true,
                         shape = RoundedCornerShape(12.dp),
                         modifier = Modifier.fillMaxWidth()

docs/aiden-on-the-go-remote-access.md

@@ -1,34 +1,38 @@
 # Aiden On The Go remote access
 
-Aiden Agent can expose a small authenticated API to Aiden On The Go on iPhone and iPad. Remote Access is off by default. Aiden must remain running on the Mac, although its window may be closed.
+Aiden Agent can expose a small authenticated API to Aiden On The Go on phones and tablets. Phone access is off by default. Aiden must remain running on the Mac, although its window may be closed.
 
 ## Local Network setup
 
-1. Open **Settings → Remote Access** in Aiden Agent.
-2. Choose **Local Network** or **Local Network + Tailscale**.
-3. Turn on **Enable Remote Access**.
-4. Add only the folders the phone or iPad may explore. Selecting the entire home directory requires a second confirmation on the Mac; the filesystem root is never allowed.
-5. Choose **Pair over Local Network** and scan the one-time QR code in Aiden On The Go.
+1. Open **Settings → Aiden On The Go** in Aiden Agent.
+2. Choose **On the same Wi-Fi**, then **Connect a device**.
+3. Review what Aiden will enable and choose **Enable and show code**.
+4. Scan the code in Aiden On The Go. If the camera is unavailable, use the setup code instead.
+
+After choosing the method, setup takes two desktop actions. Scanning and any phone permissions are additional steps. Existing ready connections can add a device directly. Under **Workspace access**, approve any additional folders the phone may browse; existing workspace access is unchanged. Approving the whole home folder requires a separate confirmation.
 
 The Mac advertises `_aiden-agent._tcp` with Bonjour only while Local Network access is running. LAN traffic uses a per-install P-256 HTTPS identity. The QR contains the private CA trust anchor and the server public-key pin so the mobile client can validate the hostname, certificate chain, and pinned key. A certificate renewal keeps the server key; an identity-key change requires pairing again.
 
 ## Tailscale setup
 
 Tailscale supplies reachability and network encryption, but Aiden still requires its own device credential on every request.
 
-1. Install Tailscale on the Mac and sign in to the intended tailnet.
-2. Ensure HTTPS certificates are available for the tailnet. Aiden reports this prerequisite rather than enabling it silently.
-3. In **Settings → Remote Access**, select **Tailscale** or **Local Network + Tailscale** and enable Remote Access.
-4. Review the exact command-equivalent route preview, then choose **Connect**.
-5. Pair with **Pair over Tailscale** after the stable `https://…ts.net/api/aiden/v1` address appears.
+1. Install Tailscale on the Mac and phone, sign in to the intended network, and make sure HTTPS is authorized for the Mac’s Tailscale name.
+2. Open **Settings → Aiden On The Go** and choose **Away from home**.
+3. Choose **Connect a device → Enable and show code**. Aiden turns on access, sets up its private connection, checks it, and shows the one-time code.
+4. Scan the code on your phone.
+
+Aiden checks installation, sign-in, HTTPS availability, and route ownership before setup. Missing prerequisites remain user actions. Conflicts and uncertain changes direct you to the advanced **Connection** controls; setup never silently replaces another route. If setup fails, Aiden removes only access introduced by that attempt where the outcome is known. An uncertain external change remains available for explicit verification.
+
+**This Mac settings** contains the Mac name and enable switch; **Connection** contains the saved mode and technical controls. Closing the code window stops pairing; phone access remains enabled until switched off. Removing a device’s access is separate from turning off all phone access.
 
 Aiden owns only `/api/aiden/v1`, proxies it to the loopback-only HTTP listener's matching `/api/aiden/v1` base, and verifies the resulting route. The matching target base is required because Tailscale strips the public `--set-path` prefix before proxying. On macOS, Aiden invokes Tailscale's shared app executable in its documented explicit CLI mode, so Finder and Dock launches do not depend on terminal environment variables. First-time connection works from an empty Serve configuration only after the node's exact Tailscale certificate domain proves HTTPS was already authorized. Aiden never enables Tailscale Funnel, never runs `tailscale serve reset`, never completes Tailscale authorization for you, and never changes unrelated Serve handlers. **Disconnect** removes only the exact route and target recorded by Aiden. A conflict is reported instead of being overwritten.
 
 ## Devices, credentials, and revocation
 
-Each phone or iPad receives a separate random credential. Aiden persists only a fast lookup digest, a salted scrypt digest, and redacted device metadata—not the credential or pairing secret. Pairing QR codes expire after five minutes and work once.
+Each phone or tablet receives a separate random credential. Aiden persists only a fast lookup digest, a salted scrypt digest, and redacted device metadata—not the credential or pairing secret. Pairing QR codes expire after five minutes and work once.
 
-Use **Revoke** beside a paired device to invalidate it immediately. Revocation does not rotate model-provider credentials or affect other paired devices. Pair the device again to restore access.
+Use **Remove access** beside a paired device to invalidate it immediately. Revocation does not rotate model-provider credentials or affect other paired devices. Pair the device again to restore access.
 
 ## Offline behavior
 

docs/plans/README.md

@@ -6,6 +6,7 @@ This directory is the source of truth for Aiden's implementation plans. The engi
 
 | Plan                                                                                               | Status  | Current state                                                                                                                                                                                                             |
 | -------------------------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [Nontechnical User Journey UX](nontechnical-user-journey-ux-plan.md)                              | Active | Approved ten-journey UX pass implemented for review: guided phone setup, four AI choices, two-step Create a bot, setup acknowledgements, recovery, and native pairing copy. Broader audit backlog and physical-device acceptance remain open. |
 | [Aiden Assistant](aiden-assistant-plan.md)                                                         | Partial | The dock, Markdown rendering, and confirmed provider-connection/model-pinned project-or-MCP automation creation/editing ship; settings tools and proactivity remain planned.                                              |
 | [Aiden On The Go](aiden-on-the-go-plan.md)                                                         | Active  | Version 0.1.0 build 22 is `VALID` and `IN_BETA_TESTING` for Internal Testers. Android matches iOS's app-icon switcher, Workspace hierarchy, warm scoped Bots/Usage/SSE lifecycle, Usage dashboard, image showcase/gallery, keyboard-safe elevated composer, and split Photo/File pickers. Both clients support native in-process dictation or bounded no-retention transcription by the paired Mac's local Parakeet model. iOS also ships progressive onboarding, bidirectional media, reliable mobile approvals, typed activity timelines, semantic haptics, and one-chat-per-Bot conversations with companion vision for text-only models. Physical iPad/manual permission-system-UI acceptance, privacy publication, final store assets, and external/public-release decisions remain open. |
 | [Unified Workspace Sidebar](unified-workspace-sidebar-plan.md)                                     | Active  | Phases 1 and 2 ship the unified workspace/chat outline plus a feature-negotiated, transcript-free paginated summary read on Electron, iOS/iPadOS, and Android; physical-device performance acceptance remains open. |