chore: whitelist npm files

- SOUL.md: Philosophy over bullet points, genuine vs performative help
- IDENTITY.md: Invites creativity, frames identity as discovery
- USER.md: Learning about a person, not building a dossier
- BOOTSTRAP.md: Conversational first-run, not robotic steps
- AGENTS.md: 'This folder is home' - clear, direct, practical
- TOOLS.md: Explains why separate from skills, real examples

New agents should boot with spark, not corporate drone energy. 🦞

.github/workflows/ci.yml

@@ -170,6 +170,43 @@ jobs:
             sleep $((attempt * 20))
           done
           exit 1
+  ios:
+    runs-on: macos-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          submodules: false
+
+      - name: Checkout submodules (retry)
+        run: |
+          set -euo pipefail
+          git submodule sync --recursive
+          for attempt in 1 2 3 4 5; do
+            if git -c protocol.version=2 submodule update --init --force --depth=1 --recursive; then
+              exit 0
+            fi
+            echo "Submodule update failed (attempt $attempt/5). Retrying…"
+            sleep $((attempt * 10))
+          done
+          exit 1
+
+      - name: Select Xcode 26.1
+        run: |
+          sudo xcode-select -s /Applications/Xcode_26.1.app
+          xcodebuild -version
+
+      - name: Install XcodeGen
+        run: brew install xcodegen
+
+      - name: Install SwiftLint / SwiftFormat
+        run: brew install swiftlint swiftformat
+
+      - name: Show toolchain
+        run: |
+          sw_vers
+          xcodebuild -version
+          swift --version
 
       - name: Generate iOS project
         run: |

.gitignore

@@ -16,6 +16,7 @@ bin/clawdis-mac
 bin/docs-list
 apps/macos/.build-local/
 apps/macos/.swiftpm/
+apps/shared/ClawdisKit/.swiftpm/
 Core/
 apps/ios/*.xcodeproj/
 apps/ios/*.xcworkspace/

CHANGELOG.md

@@ -1,5 +1,36 @@
 # Changelog
 
+## 2.0.0-beta2 — 2025-12-21
+
+Second beta focused on bundled gateway packaging, skills management, onboarding polish, and provider reliability.
+
+### Highlights
+- Bundled gateway packaging: bun-compiled embedded gateway, new `gateway-daemon` command, launchd support, DMG packaging (zip+DMG).
+- Skills platform: managed/bundled skills, install metadata + installers (uv), skill search + website, media/transcription helpers.
+- macOS app: new Connections settings w/ provider status + QR login, skills settings redesign w/ install targets, models list loaded from the Gateway, clearer local/remote gateway choices.
+- Web/agent UX: tool summary streaming + runtime toggle, WhatsApp QR login tool, agent steering queue, voice wake routes to main session, workspace bootstrap ritual.
+
+### Gateway & providers
+- Gateway: `models.list`, provider status events + RPC coverage, tailscale auth + PAM, bind-mode config, enriched agent WS logs, safer upgrade socket handling, fixed handshake auth crash.
+- WhatsApp Web: QR login flow improvements (logged-out clearing, wait flow), self-chat mode handling, removed batching delay, web inbox made non-blocking.
+- Telegram: normalized chat IDs with clearer error reporting.
+
+### Canvas & browser control
+- Canvas host served on Gateway port; removed standalone canvasHost port config; restored action bridge; refreshed A2UI bundle + message context; bridge canvas host for nodes.
+- A2UI full-screen gutters + status clearance after successful load to avoid overlay collisions.
+- Browser control API simplified; added MCP tool dispatch + native actions; control server can start without Playwright; hook timeouts extended.
+
+### macOS UI polish
+- Onboarding chat UI: kickoff flow, bubble tails, spacing + bottom bar refinements, window sizing tweaks, show Dock icon during onboarding.
+- Skills UI: stabilized action column, fixed install target access, refined list layout and sizing, always show CLI installer.
+- Remote/local gateway: auto-enable local gateway, clearer labels, re-ensure remote tunnel, hide local bridge discovery in remote mode.
+
+### Build, CI, deps
+- Bundled playwright-core + chromium-bidi/long; bun gateway bytecode builds; swiftformat/biome CI fixes; iOS lint script updates; Android icon/compiler updates; ignored new ClawdisKit `.swiftpm` path.
+
+### Docs
+- README architecture refresh + npm header image fix; onboarding/bootstrap steps; skills install guidance + new skills; browser/canvas control docs; bundled gateway + DMG packaging notes.
+
 ## 2.0.0-beta1 — 2025-12-19
 
 First Clawdis release post rebrand. This is a semver-major because we dropped legacy providers/agents and moved defaults to new paths while adding a full macOS companion app, a WebSocket Gateway, and an iOS node.

README.md

@@ -1,7 +1,7 @@
 # 🦞 CLAWDIS — Personal AI Assistant
 
 <p align="center">
-  <img src="docs/whatsapp-clawd.jpg" alt="CLAWDIS" width="400">
+  <img src="https://raw.githubusercontent.com/steipete/clawdis/main/docs/whatsapp-clawd.jpg" alt="CLAWDIS" width="400">
 </p>
 
 <p align="center">

appcast.xml

@@ -6,6 +6,17 @@
     <title>Clawdis Updates</title>
     <link>https://raw.githubusercontent.com/steipete/clawdis/main/appcast.xml</link>
     <description>Signed update feed for the Clawdis macOS companion app.</description>
+    <item>
+      <title>Clawdis 2.0.0-beta2</title>
+      <sparkle:releaseNotesLink>https://github.com/steipete/clawdis/releases/tag/v2.0.0-beta2</sparkle:releaseNotesLink>
+      <pubDate>Sun, 21 Dec 2025 02:25:39 +0000</pubDate>
+      <enclosure url="https://github.com/steipete/clawdis/releases/download/v2.0.0-beta2/Clawdis-2.0.0-beta2.zip"
+                 sparkle:edSignature="voRWLh2Cbg/i2KtUV6ci/MW3b7hK/u1ZPoiryKs+S36ua3xnc51R97JGwmIaToCfTHg2mgFWF7M6qppfe7YsAw=="
+                 sparkle:version="2.0.0-beta2"
+                 sparkle:shortVersionString="2.0.0-beta2"
+                 length="67435891"
+                 type="application/octet-stream" />
+    </item>
     <item>
       <title>Clawdis 2.0.0-beta1</title>
       <sparkle:releaseNotesLink>https://github.com/steipete/clawdis/releases/tag/v2.0.0-beta1</sparkle:releaseNotesLink>

apps/android/app/build.gradle.kts

@@ -38,15 +38,21 @@ android {
     targetCompatibility = JavaVersion.VERSION_17
   }
 
-  kotlinOptions {
-    jvmTarget = "17"
-  }
-
   packaging {
     resources {
       excludes += "/META-INF/{AL2.0,LGPL2.1}"
     }
   }
+
+  lint {
+    disable += setOf("IconLauncherShape")
+  }
+}
+
+kotlin {
+  compilerOptions {
+    jvmTarget.set(org.jetbrains.kotlin.gradle.dsl.JvmTarget.JVM_17)
+  }
 }
 
 dependencies {
@@ -56,7 +62,7 @@ dependencies {
 
   implementation("androidx.core:core-ktx:1.17.0")
   implementation("androidx.lifecycle:lifecycle-runtime-ktx:2.10.0")
-  implementation("androidx.activity:activity-compose:1.12.1")
+  implementation("androidx.activity:activity-compose:1.12.2")
 
   implementation("androidx.compose.ui:ui")
   implementation("androidx.compose.ui:ui-tooling-preview")

apps/android/app/src/main/AndroidManifest.xml

@@ -12,12 +12,20 @@
     <uses-permission
         android:name="android.permission.ACCESS_FINE_LOCATION"
         android:maxSdkVersion="32" />
+    <uses-permission
+        android:name="android.permission.ACCESS_COARSE_LOCATION"
+        android:maxSdkVersion="32" />
     <uses-permission android:name="android.permission.CAMERA" />
     <uses-permission android:name="android.permission.RECORD_AUDIO" />
+    <uses-feature
+        android:name="android.hardware.camera"
+        android:required="false" />
 
     <application
         android:name=".NodeApp"
         android:allowBackup="true"
+        android:dataExtractionRules="@xml/data_extraction_rules"
+        android:fullBackupContent="@xml/backup_rules"
         android:icon="@mipmap/ic_launcher"
         android:roundIcon="@mipmap/ic_launcher_round"
         android:label="@string/app_name"

apps/android/app/src/main/java/com/steipete/clawdis/node/NodeForegroundService.kt

@@ -10,7 +10,6 @@ import android.content.Context
 import android.content.Intent
 import android.content.pm.PackageManager
 import android.content.pm.ServiceInfo
-import android.os.Build
 import androidx.core.app.NotificationCompat
 import androidx.core.content.ContextCompat
 import kotlinx.coroutines.CoroutineScope
@@ -85,7 +84,6 @@ class NodeForegroundService : Service() {
   override fun onBind(intent: Intent?) = null
 
   private fun ensureChannel() {
-    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
     val mgr = getSystemService(NotificationManager::class.java)
     val channel =
       NotificationChannel(
@@ -101,12 +99,7 @@ class NodeForegroundService : Service() {
 
   private fun buildNotification(title: String, text: String): Notification {
     val stopIntent = Intent(this, NodeForegroundService::class.java).setAction(ACTION_STOP)
-    val flags =
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
-      } else {
-        PendingIntent.FLAG_UPDATE_CURRENT
-      }
+    val flags = PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
     val stopPending = PendingIntent.getService(this, 2, stopIntent, flags)
 
     return NotificationCompat.Builder(this, CHANNEL_ID)
@@ -126,11 +119,6 @@ class NodeForegroundService : Service() {
   }
 
   private fun startForegroundWithTypes(notification: Notification, requiresMic: Boolean) {
-    if (Build.VERSION.SDK_INT < 29) {
-      startForeground(NOTIFICATION_ID, notification)
-      return
-    }
-
     if (didStartForeground && requiresMic == lastRequiresMic) {
       updateNotification(notification)
       return
@@ -162,11 +150,7 @@ class NodeForegroundService : Service() {
 
     fun start(context: Context) {
       val intent = Intent(context, NodeForegroundService::class.java)
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-        context.startForegroundService(intent)
-      } else {
-        context.startService(intent)
-      }
+      context.startForegroundService(intent)
     }
 
     fun stop(context: Context) {

apps/android/app/src/main/java/com/steipete/clawdis/node/NodeRuntime.kt

@@ -396,8 +396,7 @@ class NodeRuntime(context: Context) {
       val actionId = (userActionObj["id"] as? JsonPrimitive)?.content?.trim().orEmpty().ifEmpty {
         java.util.UUID.randomUUID().toString()
       }
-      val name = (userActionObj["name"] as? JsonPrimitive)?.content?.trim().orEmpty()
-      if (name.isEmpty()) return@launch
+      val name = ClawdisCanvasA2UIAction.extractActionName(userActionObj) ?: return@launch
 
       val surfaceId =
         (userActionObj["surfaceId"] as? JsonPrimitive)?.content?.trim().orEmpty().ifEmpty { "main" }

apps/android/app/src/main/java/com/steipete/clawdis/node/SecurePrefs.kt

@@ -3,6 +3,7 @@
 package com.steipete.clawdis.node
 
 import android.content.Context
+import androidx.core.content.edit
 import androidx.security.crypto.EncryptedSharedPreferences
 import androidx.security.crypto.MasterKey
 import kotlinx.coroutines.flow.MutableStateFlow
@@ -70,39 +71,39 @@ class SecurePrefs(context: Context) {
 
   fun setLastDiscoveredStableId(value: String) {
     val trimmed = value.trim()
-    prefs.edit().putString("bridge.lastDiscoveredStableId", trimmed).apply()
+    prefs.edit { putString("bridge.lastDiscoveredStableId", trimmed) }
     _lastDiscoveredStableId.value = trimmed
   }
 
   fun setDisplayName(value: String) {
     val trimmed = value.trim()
-    prefs.edit().putString(displayNameKey, trimmed).apply()
+    prefs.edit { putString(displayNameKey, trimmed) }
     _displayName.value = trimmed
   }
 
   fun setCameraEnabled(value: Boolean) {
-    prefs.edit().putBoolean("camera.enabled", value).apply()
+    prefs.edit { putBoolean("camera.enabled", value) }
     _cameraEnabled.value = value
   }
 
   fun setPreventSleep(value: Boolean) {
-    prefs.edit().putBoolean("screen.preventSleep", value).apply()
+    prefs.edit { putBoolean("screen.preventSleep", value) }
     _preventSleep.value = value
   }
 
   fun setManualEnabled(value: Boolean) {
-    prefs.edit().putBoolean("bridge.manual.enabled", value).apply()
+    prefs.edit { putBoolean("bridge.manual.enabled", value) }
     _manualEnabled.value = value
   }
 
   fun setManualHost(value: String) {
     val trimmed = value.trim()
-    prefs.edit().putString("bridge.manual.host", trimmed).apply()
+    prefs.edit { putString("bridge.manual.host", trimmed) }
     _manualHost.value = trimmed
   }
 
   fun setManualPort(value: Int) {
-    prefs.edit().putInt("bridge.manual.port", value).apply()
+    prefs.edit { putInt("bridge.manual.port", value) }
     _manualPort.value = value
   }
 
@@ -113,14 +114,14 @@ class SecurePrefs(context: Context) {
 
   fun saveBridgeToken(token: String) {
     val key = "bridge.token.${_instanceId.value}"
-    prefs.edit().putString(key, token.trim()).apply()
+    prefs.edit { putString(key, token.trim()) }
   }
 
   private fun loadOrCreateInstanceId(): String {
     val existing = prefs.getString("node.instanceId", null)?.trim()
     if (!existing.isNullOrBlank()) return existing
     val fresh = UUID.randomUUID().toString()
-    prefs.edit().putString("node.instanceId", fresh).apply()
+    prefs.edit { putString("node.instanceId", fresh) }
     return fresh
   }
 
@@ -131,7 +132,7 @@ class SecurePrefs(context: Context) {
     val candidate = DeviceNames.bestDefaultNodeName(context).trim()
     val resolved = candidate.ifEmpty { "Android Node" }
 
-    prefs.edit().putString(displayNameKey, resolved).apply()
+    prefs.edit { putString(displayNameKey, resolved) }
     return resolved
   }
 
@@ -139,12 +140,12 @@ class SecurePrefs(context: Context) {
     val sanitized = WakeWords.sanitize(words, defaultWakeWords)
     val encoded =
       JsonArray(sanitized.map { JsonPrimitive(it) }).toString()
-    prefs.edit().putString("voiceWake.triggerWords", encoded).apply()
+    prefs.edit { putString("voiceWake.triggerWords", encoded) }
     _wakeWords.value = sanitized
   }
 
   fun setVoiceWakeMode(mode: VoiceWakeMode) {
-    prefs.edit().putString(voiceWakeModeKey, mode.rawValue).apply()
+    prefs.edit { putString(voiceWakeModeKey, mode.rawValue) }
     _voiceWakeMode.value = mode
   }
 
@@ -154,7 +155,7 @@ class SecurePrefs(context: Context) {
 
     // Default ON (foreground) when unset.
     if (raw.isNullOrBlank()) {
-      prefs.edit().putString(voiceWakeModeKey, resolved.rawValue).apply()
+      prefs.edit { putString(voiceWakeModeKey, resolved.rawValue) }
     }
 
     return resolved

apps/android/app/src/main/java/com/steipete/clawdis/node/bridge/BridgeDiscovery.kt

@@ -6,7 +6,6 @@ import android.net.DnsResolver
 import android.net.NetworkCapabilities
 import android.net.nsd.NsdManager
 import android.net.nsd.NsdServiceInfo
-import android.os.Build
 import android.os.CancellationSignal
 import android.util.Log
 import java.io.IOException
@@ -44,6 +43,7 @@ import org.xbill.DNS.Type
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 
+@Suppress("DEPRECATION")
 class BridgeDiscovery(
   context: Context,
   private val scope: CoroutineScope,
@@ -181,7 +181,6 @@ class BridgeDiscovery(
   }
 
   private fun txt(info: NsdServiceInfo, key: String): String? {
-    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.LOLLIPOP) return null
     val bytes = info.attributes[key] ?: return null
     return try {
       String(bytes, Charsets.UTF_8).trim().ifEmpty { null }
@@ -401,7 +400,7 @@ class BridgeDiscovery(
       dns.rawQuery(
         network,
         wireQuery,
-        0,
+        DnsResolver.FLAG_EMPTY,
         dnsExecutor,
         signal,
         object : DnsResolver.Callback<ByteArray> {

apps/android/app/src/main/java/com/steipete/clawdis/node/node/CameraCaptureManager.kt

@@ -2,6 +2,7 @@ package com.steipete.clawdis.node.node
 
 import android.Manifest
 import android.content.Context
+import android.annotation.SuppressLint
 import android.graphics.Bitmap
 import android.graphics.BitmapFactory
 import android.util.Base64
@@ -18,6 +19,7 @@ import androidx.camera.video.VideoCapture
 import androidx.camera.video.VideoRecordEvent
 import androidx.core.content.ContextCompat
 import androidx.core.content.ContextCompat.checkSelfPermission
+import androidx.core.graphics.scale
 import com.steipete.clawdis.node.PermissionRequester
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.suspendCancellableCoroutine
@@ -92,7 +94,7 @@ class CameraCaptureManager(private val context: Context) {
             (decoded.height.toDouble() * (maxWidth.toDouble() / decoded.width.toDouble()))
               .toInt()
               .coerceAtLeast(1)
-          Bitmap.createScaledBitmap(decoded, maxWidth, h, true)
+          decoded.scale(maxWidth, h)
         } else {
           decoded
         }
@@ -108,6 +110,7 @@ class CameraCaptureManager(private val context: Context) {
       )
     }
 
+  @SuppressLint("MissingPermission")
   suspend fun clip(paramsJson: String?): Payload =
     withContext(Dispatchers.Main) {
       ensureCameraPermission()

apps/android/app/src/main/java/com/steipete/clawdis/node/node/CanvasController.kt

@@ -1,10 +1,11 @@
 package com.steipete.clawdis.node.node
 
 import android.graphics.Bitmap
-import android.os.Build
 import android.graphics.Canvas
 import android.os.Looper
 import android.webkit.WebView
+import androidx.core.graphics.createBitmap
+import androidx.core.graphics.scale
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.suspendCancellableCoroutine
 import kotlinx.coroutines.withContext
@@ -80,7 +81,7 @@ class CanvasController {
       val scaled =
         if (maxWidth != null && maxWidth > 0 && bmp.width > maxWidth) {
           val h = (bmp.height.toDouble() * (maxWidth.toDouble() / bmp.width.toDouble())).toInt().coerceAtLeast(1)
-          Bitmap.createScaledBitmap(bmp, maxWidth, h, true)
+          bmp.scale(maxWidth, h)
         } else {
           bmp
         }
@@ -97,7 +98,7 @@ class CanvasController {
       val scaled =
         if (maxWidth != null && maxWidth > 0 && bmp.width > maxWidth) {
           val h = (bmp.height.toDouble() * (maxWidth.toDouble() / bmp.width.toDouble())).toInt().coerceAtLeast(1)
-          Bitmap.createScaledBitmap(bmp, maxWidth, h, true)
+          bmp.scale(maxWidth, h)
         } else {
           bmp
         }
@@ -116,7 +117,7 @@ class CanvasController {
     suspendCancellableCoroutine { cont ->
       val width = width.coerceAtLeast(1)
       val height = height.coerceAtLeast(1)
-      val bitmap = Bitmap.createBitmap(width, height, Bitmap.Config.ARGB_8888)
+      val bitmap = createBitmap(width, height, Bitmap.Config.ARGB_8888)
 
       // WebView isn't supported by PixelCopy.request(...) directly; draw() is the most reliable
       // cross-version snapshot for this lightweight "canvas" use-case.

apps/android/app/src/main/java/com/steipete/clawdis/node/protocol/ClawdisCanvasA2UIAction.kt

@@ -1,6 +1,24 @@
 package com.steipete.clawdis.node.protocol
 
+import kotlinx.serialization.json.JsonObject
+import kotlinx.serialization.json.JsonPrimitive
+
 object ClawdisCanvasA2UIAction {
+  fun extractActionName(userAction: JsonObject): String? {
+    val name =
+      (userAction["name"] as? JsonPrimitive)
+        ?.content
+        ?.trim()
+        .orEmpty()
+    if (name.isNotEmpty()) return name
+    val action =
+      (userAction["action"] as? JsonPrimitive)
+        ?.content
+        ?.trim()
+        .orEmpty()
+    return action.ifEmpty { null }
+  }
+
   fun sanitizeTagValue(value: String): String {
     val trimmed = value.trim().ifEmpty { "-" }
     val normalized = trimmed.replace(" ", "_")
@@ -46,4 +64,3 @@ object ClawdisCanvasA2UIAction {
     return "window.dispatchEvent(new CustomEvent('clawdis:a2ui-action-status', { detail: { id: \"${idEscaped}\", ok: ${okLiteral}, error: \"${err}\" } }));"
   }
 }
-

apps/android/app/src/main/java/com/steipete/clawdis/node/ui/RootScreen.kt

@@ -191,11 +191,14 @@ private fun CanvasView(viewModel: MainViewModel, modifier: Modifier = Modifier)
         setBackgroundColor(Color.BLACK)
         setLayerType(View.LAYER_TYPE_HARDWARE, null)
 
-        addJavascriptInterface(
+        val a2uiBridge =
           CanvasA2UIActionBridge { payload ->
             viewModel.handleCanvasA2UIActionFromWebView(payload)
-          },
-          CanvasA2UIActionBridge.interfaceName,
+          }
+        addJavascriptInterface(a2uiBridge, CanvasA2UIActionBridge.interfaceName)
+        addJavascriptInterface(
+          CanvasA2UIActionLegacyBridge(a2uiBridge),
+          CanvasA2UIActionLegacyBridge.interfaceName,
         )
         viewModel.canvas.attach(this)
       }
@@ -215,3 +218,19 @@ private class CanvasA2UIActionBridge(private val onMessage: (String) -> Unit) {
     const val interfaceName: String = "clawdisCanvasA2UIAction"
   }
 }
+
+private class CanvasA2UIActionLegacyBridge(private val bridge: CanvasA2UIActionBridge) {
+  @JavascriptInterface
+  fun canvasAction(payload: String?) {
+    bridge.postMessage(payload)
+  }
+
+  @JavascriptInterface
+  fun postMessage(payload: String?) {
+    bridge.postMessage(payload)
+  }
+
+  companion object {
+    const val interfaceName: String = "Android"
+  }
+}

apps/android/app/src/main/res/mipmap-anydpi/ic_launcher.xml

@@ -2,5 +2,5 @@
 <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
     <background android:drawable="@color/ic_launcher_background" />
     <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+    <monochrome android:drawable="@mipmap/ic_launcher_foreground" />
 </adaptive-icon>
-

apps/android/app/src/main/res/mipmap-anydpi/ic_launcher_round.xml

@@ -2,5 +2,5 @@
 <adaptive-icon xmlns:android="http://schemas.android.com/apk/res/android">
     <background android:drawable="@color/ic_launcher_background" />
     <foreground android:drawable="@mipmap/ic_launcher_foreground" />
+    <monochrome android:drawable="@mipmap/ic_launcher_foreground" />
 </adaptive-icon>
-

apps/android/app/src/main/res/values/themes.xml

@@ -1,8 +1,7 @@
-<resources xmlns:tools="http://schemas.android.com/tools">
+<resources>
     <style name="Theme.ClawdisNode" parent="Theme.Material3.DayNight.NoActionBar">
         <item name="android:statusBarColor">@android:color/transparent</item>
         <item name="android:navigationBarColor">@android:color/transparent</item>
-        <item name="android:windowLightStatusBar" tools:targetApi="m">false</item>
+        <item name="android:windowLightStatusBar">false</item>
     </style>
 </resources>
-

apps/android/app/src/main/res/xml/backup_rules.xml

@@ -0,0 +1,4 @@
+<?xml version="1.0" encoding="utf-8"?>
+<full-backup-content>
+  <include domain="file" path="." />
+</full-backup-content>

apps/android/app/src/main/res/xml/data_extraction_rules.xml

@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="utf-8"?>
+<data-extraction-rules>
+  <cloud-backup>
+    <include domain="file" path="." />
+  </cloud-backup>
+  <device-transfer>
+    <include domain="file" path="." />
+  </device-transfer>
+</data-extraction-rules>

apps/android/app/src/main/res/xml/network_security_config.xml

@@ -1,7 +1,7 @@
 <?xml version="1.0" encoding="utf-8"?>
-<network-security-config>
+<network-security-config xmlns:tools="http://schemas.android.com/tools">
   <!-- This app is primarily used on a trusted tailnet; allow cleartext for IP-based endpoints too. -->
-  <base-config cleartextTrafficPermitted="true" />
+  <base-config cleartextTrafficPermitted="true" tools:ignore="InsecureBaseConfiguration" />
   <!-- Allow HTTP for tailnet/local dev endpoints (e.g. canvas/background web). -->
   <domain-config cleartextTrafficPermitted="true">
     <domain includeSubdomains="true">clawdis.internal</domain>

apps/android/app/src/test/java/com/steipete/clawdis/node/protocol/ClawdisCanvasA2UIActionTest.kt

@@ -1,9 +1,24 @@
 package com.steipete.clawdis.node.protocol
 
+import kotlinx.serialization.json.Json
+import kotlinx.serialization.json.jsonObject
 import org.junit.Assert.assertEquals
 import org.junit.Test
 
 class ClawdisCanvasA2UIActionTest {
+  @Test
+  fun extractActionNameAcceptsNameOrAction() {
+    val nameObj = Json.parseToJsonElement("{\"name\":\"Hello\"}").jsonObject
+    assertEquals("Hello", ClawdisCanvasA2UIAction.extractActionName(nameObj))
+
+    val actionObj = Json.parseToJsonElement("{\"action\":\"Wave\"}").jsonObject
+    assertEquals("Wave", ClawdisCanvasA2UIAction.extractActionName(actionObj))
+
+    val fallbackObj =
+      Json.parseToJsonElement("{\"name\":\"  \",\"action\":\"Fallback\"}").jsonObject
+    assertEquals("Fallback", ClawdisCanvasA2UIAction.extractActionName(fallbackObj))
+  }
+
   @Test
   fun formatAgentMessageMatchesSharedSpec() {
     val msg =
@@ -32,4 +47,3 @@ class ClawdisCanvasA2UIActionTest {
     )
   }
 }
-

apps/ios/Sources/Info.plist

@@ -22,6 +22,11 @@
 	<string>1.0</string>
 	<key>CFBundleVersion</key>
 	<string>1</string>
+	<key>NSAppTransportSecurity</key>
+	<dict>
+		<key>NSAllowsArbitraryLoadsInWebContent</key>
+		<true/>
+	</dict>
 	<key>NSBonjourServices</key>
 	<array>
 		<string>_clawdis-bridge._tcp</string>

apps/ios/Sources/Model/NodeAppModel.swift

@@ -80,7 +80,7 @@ final class NodeAppModel {
         }()
         guard !userAction.isEmpty else { return }
 
-        guard let name = userAction["name"] as? String, !name.isEmpty else { return }
+        guard let name = ClawdisCanvasA2UIAction.extractActionName(userAction) else { return }
         let actionId: String = {
             let id = (userAction["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines) ?? ""
             return id.isEmpty ? UUID().uuidString : id
@@ -102,14 +102,12 @@ final class NodeAppModel {
         let contextJSON = ClawdisCanvasA2UIAction.compactJSON(userAction["context"])
         let sessionKey = "main"
 
-        let message = ClawdisCanvasA2UIAction.formatAgentMessage(
+        let messageContext = ClawdisCanvasA2UIAction.AgentMessageContext(
             actionName: name,
-            sessionKey: sessionKey,
-            surfaceId: surfaceId,
-            sourceComponentId: sourceComponentId,
-            host: host,
-            instanceId: instanceId,
+            session: .init(key: sessionKey, surfaceId: surfaceId),
+            component: .init(id: sourceComponentId, host: host, instanceId: instanceId),
             contextJSON: contextJSON)
+        let message = ClawdisCanvasA2UIAction.formatAgentMessage(messageContext)
 
         let ok: Bool
         var errorText: String?

apps/ios/Sources/Screen/ScreenController.swift

@@ -24,7 +24,9 @@ final class ScreenController {
         config.websiteDataStore = .nonPersistent()
         let a2uiActionHandler = CanvasA2UIActionMessageHandler()
         let userContentController = WKUserContentController()
-        userContentController.add(a2uiActionHandler, name: CanvasA2UIActionMessageHandler.messageName)
+        for name in CanvasA2UIActionMessageHandler.handlerNames {
+            userContentController.add(a2uiActionHandler, name: name)
+        }
         config.userContentController = userContentController
         self.navigationDelegate = ScreenNavigationDelegate()
         self.a2uiActionHandler = a2uiActionHandler
@@ -316,6 +318,10 @@ private final class ScreenNavigationDelegate: NSObject, WKNavigationDelegate {
         self.controller?.errorText = error.localizedDescription
     }
 
+    func webView(_: WKWebView, didFinish _: WKNavigation?) {
+        self.controller?.errorText = nil
+    }
+
     func webView(_: WKWebView, didFail _: WKNavigation?, withError error: any Error) {
         self.controller?.errorText = error.localizedDescription
     }
@@ -323,6 +329,8 @@ private final class ScreenNavigationDelegate: NSObject, WKNavigationDelegate {
 
 private final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHandler {
     static let messageName = "clawdisCanvasA2UIAction"
+    static let legacyMessageNames = ["canvas", "a2ui", "userAction", "action"]
+    static let handlerNames = [messageName] + legacyMessageNames
 
     weak var controller: ScreenController?
 

apps/ios/SwiftSources.input.xcfilelist

@@ -0,0 +1,56 @@
+Sources/Bridge/BridgeClient.swift
+Sources/Bridge/BridgeConnectionController.swift
+Sources/Bridge/BridgeDiscoveryDebugLogView.swift
+Sources/Bridge/BridgeDiscoveryModel.swift
+Sources/Bridge/BridgeEndpointID.swift
+Sources/Bridge/BridgeSession.swift
+Sources/Bridge/BridgeSettingsStore.swift
+Sources/Bridge/KeychainStore.swift
+Sources/Camera/CameraController.swift
+Sources/Chat/ChatSheet.swift
+Sources/Chat/IOSBridgeChatTransport.swift
+Sources/ClawdisApp.swift
+Sources/Model/NodeAppModel.swift
+Sources/RootCanvas.swift
+Sources/RootTabs.swift
+Sources/Screen/ScreenController.swift
+Sources/Screen/ScreenRecordService.swift
+Sources/Screen/ScreenTab.swift
+Sources/Screen/ScreenWebView.swift
+Sources/Settings/SettingsNetworkingHelpers.swift
+Sources/Settings/SettingsTab.swift
+Sources/Settings/VoiceWakeWordsSettingsView.swift
+Sources/Status/StatusPill.swift
+Sources/Status/VoiceWakeToast.swift
+Sources/Voice/VoiceTab.swift
+Sources/Voice/VoiceWakeManager.swift
+Sources/Voice/VoiceWakePreferences.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatComposer.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatMarkdownSplitter.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatMessageViews.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatModels.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatPayloadDecoding.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatSessions.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatSheets.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatTheme.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatTransport.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatView.swift
+../shared/ClawdisKit/Sources/ClawdisChatUI/ChatViewModel.swift
+../shared/ClawdisKit/Sources/ClawdisKit/AnyCodable.swift
+../shared/ClawdisKit/Sources/ClawdisKit/BonjourEscapes.swift
+../shared/ClawdisKit/Sources/ClawdisKit/BonjourTypes.swift
+../shared/ClawdisKit/Sources/ClawdisKit/BridgeFrames.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CameraCommands.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasA2UIAction.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasA2UICommands.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasA2UIJSONL.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasCommandParams.swift
+../shared/ClawdisKit/Sources/ClawdisKit/CanvasCommands.swift
+../shared/ClawdisKit/Sources/ClawdisKit/Capabilities.swift
+../shared/ClawdisKit/Sources/ClawdisKit/ClawdisKitResources.swift
+../shared/ClawdisKit/Sources/ClawdisKit/DeepLinks.swift
+../shared/ClawdisKit/Sources/ClawdisKit/JPEGTranscoder.swift
+../shared/ClawdisKit/Sources/ClawdisKit/NodeError.swift
+../shared/ClawdisKit/Sources/ClawdisKit/ScreenCommands.swift
+../shared/ClawdisKit/Sources/ClawdisKit/StoragePaths.swift
+../shared/ClawdisKit/Sources/ClawdisKit/SystemCommands.swift

apps/ios/project.yml

@@ -29,27 +29,33 @@ targets:
       - package: ClawdisKit
       - package: ClawdisKit
         product: ClawdisChatUI
+      - sdk: AppIntents.framework
     preBuildScripts:
       - name: SwiftFormat (lint)
         basedOnDependencyAnalysis: false
+        inputFileLists:
+          - $(SRCROOT)/SwiftSources.input.xcfilelist
         script: |
           set -euo pipefail
+          export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
           if ! command -v swiftformat >/dev/null 2>&1; then
             echo "error: swiftformat not found (brew install swiftformat)" >&2
             exit 1
           fi
           swiftformat --lint --config "$SRCROOT/../../.swiftformat" \
-            "$SRCROOT/Sources" \
-            "$SRCROOT/../shared/ClawdisKit/Sources"
+            --filelist "$SRCROOT/SwiftSources.input.xcfilelist"
       - name: SwiftLint
         basedOnDependencyAnalysis: false
+        inputFileLists:
+          - $(SRCROOT)/SwiftSources.input.xcfilelist
         script: |
           set -euo pipefail
+          export PATH="/opt/homebrew/bin:/usr/local/bin:$PATH"
           if ! command -v swiftlint >/dev/null 2>&1; then
             echo "error: swiftlint not found (brew install swiftlint)" >&2
             exit 1
           fi
-          swiftlint lint --config "$SRCROOT/.swiftlint.yml"
+          swiftlint lint --config "$SRCROOT/.swiftlint.yml" --use-script-input-file-lists
     settings:
       base:
         PRODUCT_BUNDLE_IDENTIFIER: com.steipete.clawdis.ios
@@ -65,6 +71,8 @@ targets:
         UIBackgroundModes:
           - audio
         NSLocalNetworkUsageDescription: Clawdis discovers and connects to your Clawdis bridge on the local network.
+        NSAppTransportSecurity:
+          NSAllowsArbitraryLoadsInWebContent: true
         NSBonjourServices:
           - _clawdis-bridge._tcp
         NSCameraUsageDescription: Clawdis can capture photos or short video clips when requested via the bridge.

apps/macos/Sources/Clawdis/AgentIdentity.swift

@@ -1,45 +0,0 @@
-import Foundation
-
-struct AgentIdentity: Codable, Equatable {
-    var name: String
-    var theme: String
-    var emoji: String
-
-    var isEmpty: Bool {
-        self.name.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty &&
-            self.theme.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty &&
-            self.emoji.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty
-    }
-}
-
-enum AgentIdentityEmoji {
-    static func suggest(theme: String) -> String {
-        let normalized = theme.trimmingCharacters(in: .whitespacesAndNewlines).lowercased()
-        if normalized.isEmpty { return "🦞" }
-
-        let table: [(needle: String, emoji: String)] = [
-            ("lobster", "🦞"),
-            ("sloth", "🦥"),
-            ("octopus", "🐙"),
-            ("crab", "🦀"),
-            ("shark", "🦈"),
-            ("cat", "🐈"),
-            ("dog", "🐕"),
-            ("owl", "🦉"),
-            ("fox", "🦊"),
-            ("otter", "🦦"),
-            ("raccoon", "🦝"),
-            ("badger", "🦡"),
-            ("hedgehog", "🦔"),
-            ("koala", "🐨"),
-            ("penguin", "🐧"),
-            ("frog", "🐸"),
-            ("bear", "🐻"),
-        ]
-
-        for entry in table where normalized.contains(entry.needle) {
-            return entry.emoji
-        }
-        return "🦞"
-    }
-}

apps/macos/Sources/Clawdis/AgentWorkspace.swift

@@ -9,8 +9,18 @@ enum AgentWorkspace {
     static let userFilename = "USER.md"
     static let bootstrapFilename = "BOOTSTRAP.md"
     private static let templateDirname = "templates"
-    static let identityStartMarker = "<!-- clawdis:identity:start -->"
-    static let identityEndMarker = "<!-- clawdis:identity:end -->"
+    private static let ignoredEntries: Set<String> = [".DS_Store", ".git", ".gitignore"]
+    private static let templateEntries: Set<String> = [
+        AgentWorkspace.agentsFilename,
+        AgentWorkspace.soulFilename,
+        AgentWorkspace.identityFilename,
+        AgentWorkspace.userFilename,
+        AgentWorkspace.bootstrapFilename,
+    ]
+    enum BootstrapSafety: Equatable {
+        case safe
+        case unsafe(reason: String)
+    }
 
     static func displayPath(for url: URL) -> String {
         let home = FileManager.default.homeDirectoryForCurrentUser.path
@@ -33,7 +43,53 @@ enum AgentWorkspace {
         workspaceURL.appendingPathComponent(self.agentsFilename)
     }
 
+    static func workspaceEntries(workspaceURL: URL) throws -> [String] {
+        let contents = try FileManager.default.contentsOfDirectory(atPath: workspaceURL.path)
+        return contents.filter { !self.ignoredEntries.contains($0) }
+    }
+
+    static func isWorkspaceEmpty(workspaceURL: URL) -> Bool {
+        let fm = FileManager.default
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return true
+        }
+        guard isDir.boolValue else { return false }
+        guard let entries = try? self.workspaceEntries(workspaceURL: workspaceURL) else { return false }
+        return entries.isEmpty
+    }
+
+    static func isTemplateOnlyWorkspace(workspaceURL: URL) -> Bool {
+        guard let entries = try? self.workspaceEntries(workspaceURL: workspaceURL) else { return false }
+        guard !entries.isEmpty else { return true }
+        return Set(entries).isSubset(of: self.templateEntries)
+    }
+
+    static func bootstrapSafety(for workspaceURL: URL) -> BootstrapSafety {
+        let fm = FileManager.default
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return .safe
+        }
+        if !isDir.boolValue {
+            return .unsafe(reason: "Workspace path points to a file.")
+        }
+        let agentsURL = self.agentsURL(workspaceURL: workspaceURL)
+        if fm.fileExists(atPath: agentsURL.path) {
+            return .safe
+        }
+        do {
+            let entries = try self.workspaceEntries(workspaceURL: workspaceURL)
+            return entries.isEmpty
+                ? .safe
+                : .unsafe(reason: "Folder isn't empty. Choose a new folder or add AGENTS.md first.")
+        } catch {
+            return .unsafe(reason: "Couldn't inspect the workspace folder.")
+        }
+    }
+
     static func bootstrap(workspaceURL: URL) throws -> URL {
+        let shouldSeedBootstrap = self.isWorkspaceEmpty(workspaceURL: workspaceURL)
         try FileManager.default.createDirectory(at: workspaceURL, withIntermediateDirectories: true)
         let agentsURL = self.agentsURL(workspaceURL: workspaceURL)
         if !FileManager.default.fileExists(atPath: agentsURL.path) {
@@ -56,36 +112,44 @@ enum AgentWorkspace {
             self.logger.info("Created USER.md at \(userURL.path, privacy: .public)")
         }
         let bootstrapURL = workspaceURL.appendingPathComponent(self.bootstrapFilename)
-        if !FileManager.default.fileExists(atPath: bootstrapURL.path) {
+        if shouldSeedBootstrap, !FileManager.default.fileExists(atPath: bootstrapURL.path) {
             try self.defaultBootstrapTemplate().write(to: bootstrapURL, atomically: true, encoding: .utf8)
             self.logger.info("Created BOOTSTRAP.md at \(bootstrapURL.path, privacy: .public)")
         }
         return agentsURL
     }
 
-    static func upsertIdentity(workspaceURL: URL, identity: AgentIdentity) throws {
-        let agentsURL = try self.bootstrap(workspaceURL: workspaceURL)
-        var content = (try? String(contentsOf: agentsURL, encoding: .utf8)) ?? ""
-        let block = self.identityBlock(identity: identity)
-
-        if let start = content.range(of: self.identityStartMarker),
-           let end = content.range(of: self.identityEndMarker),
-           start.lowerBound < end.upperBound
-        {
-            content.replaceSubrange(
-                start.lowerBound..<end.upperBound,
-                with: block.trimmingCharacters(in: .whitespacesAndNewlines))
-        } else if let insert = self.identityInsertRange(in: content) {
-            content.insert(contentsOf: "\n\n## Identity\n\(block)\n", at: insert.upperBound)
-        } else {
-            content = [content.trimmingCharacters(in: .whitespacesAndNewlines), "## Identity\n\(block)"]
-                .filter { !$0.isEmpty }
-                .joined(separator: "\n\n")
-                .appending("\n")
+    static func needsBootstrap(workspaceURL: URL) -> Bool {
+        let fm = FileManager.default
+        var isDir: ObjCBool = false
+        if !fm.fileExists(atPath: workspaceURL.path, isDirectory: &isDir) {
+            return true
         }
+        guard isDir.boolValue else { return true }
+        if self.hasIdentity(workspaceURL: workspaceURL) {
+            return false
+        }
+        let bootstrapURL = workspaceURL.appendingPathComponent(self.bootstrapFilename)
+        guard fm.fileExists(atPath: bootstrapURL.path) else { return false }
+        return self.isTemplateOnlyWorkspace(workspaceURL: workspaceURL)
+    }
 
-        try content.write(to: agentsURL, atomically: true, encoding: .utf8)
-        self.logger.info("Updated identity in \(agentsURL.path, privacy: .public)")
+    static func hasIdentity(workspaceURL: URL) -> Bool {
+        let identityURL = workspaceURL.appendingPathComponent(self.identityFilename)
+        guard let contents = try? String(contentsOf: identityURL, encoding: .utf8) else { return false }
+        return self.identityLinesHaveValues(contents)
+    }
+
+    private static func identityLinesHaveValues(_ content: String) -> Bool {
+        for line in content.split(separator: "\n") {
+            let trimmed = line.trimmingCharacters(in: .whitespacesAndNewlines)
+            guard trimmed.hasPrefix("-"), let colon = trimmed.firstIndex(of: ":") else { continue }
+            let value = trimmed[trimmed.index(after: colon)...].trimmingCharacters(in: .whitespacesAndNewlines)
+            if !value.isEmpty {
+                return true
+            }
+        }
+        return false
     }
 
     static func defaultTemplate() -> String {
@@ -272,25 +336,5 @@ enum AgentWorkspace {
         return trimmed + "\n"
     }
 
-    private static func identityBlock(identity: AgentIdentity) -> String {
-        let name = identity.name.trimmingCharacters(in: .whitespacesAndNewlines)
-        let theme = identity.theme.trimmingCharacters(in: .whitespacesAndNewlines)
-        let emoji = identity.emoji.trimmingCharacters(in: .whitespacesAndNewlines)
-
-        return """
-        \(self.identityStartMarker)
-        - Name: \(name)
-        - Theme: \(theme)
-        - Emoji: \(emoji)
-        \(self.identityEndMarker)
-        """
-    }
-
-    private static func identityInsertRange(in content: String) -> Range<String.Index>? {
-        if let firstHeading = content.range(of: "\n") {
-            // Insert after the first line (usually "# AGENTS.md …")
-            return firstHeading
-        }
-        return nil
-    }
+    // Identity is written by the agent during the bootstrap ritual.
 }

apps/macos/Sources/Clawdis/AnyCodable+Helpers.swift

@@ -0,0 +1,22 @@
+import ClawdisProtocol
+import Foundation
+
+extension AnyCodable {
+    var stringValue: String? { self.value as? String }
+    var boolValue: Bool? { self.value as? Bool }
+    var intValue: Int? { self.value as? Int }
+    var doubleValue: Double? { self.value as? Double }
+    var dictionaryValue: [String: AnyCodable]? { self.value as? [String: AnyCodable] }
+    var arrayValue: [AnyCodable]? { self.value as? [AnyCodable] }
+
+    var foundationValue: Any {
+        switch self.value {
+        case let dict as [String: AnyCodable]:
+            dict.mapValues { $0.foundationValue }
+        case let array as [AnyCodable]:
+            array.map(\.foundationValue)
+        default:
+            self.value
+        }
+    }
+}

apps/macos/Sources/Clawdis/CanvasWindow.swift

@@ -639,7 +639,7 @@ private final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHan
         }()
         guard !userAction.isEmpty else { return }
 
-        guard let name = userAction["name"] as? String, !name.isEmpty else { return }
+        guard let name = ClawdisCanvasA2UIAction.extractActionName(userAction) else { return }
         let actionId =
             (userAction["id"] as? String)?.trimmingCharacters(in: .whitespacesAndNewlines).nonEmpty
                 ?? UUID().uuidString
@@ -654,14 +654,12 @@ private final class CanvasA2UIActionMessageHandler: NSObject, WKScriptMessageHan
         let contextJSON = ClawdisCanvasA2UIAction.compactJSON(userAction["context"])
 
         // Token-efficient and unambiguous. The agent should treat this as a UI event and (by default) update Canvas.
-        let text = ClawdisCanvasA2UIAction.formatAgentMessage(
+        let messageContext = ClawdisCanvasA2UIAction.AgentMessageContext(
             actionName: name,
-            sessionKey: self.sessionKey,
-            surfaceId: surfaceId,
-            sourceComponentId: sourceComponentId,
-            host: InstanceIdentity.displayName,
-            instanceId: instanceId,
+            session: .init(key: self.sessionKey, surfaceId: surfaceId),
+            component: .init(id: sourceComponentId, host: InstanceIdentity.displayName, instanceId: instanceId),
             contextJSON: contextJSON)
+        let text = ClawdisCanvasA2UIAction.formatAgentMessage(messageContext)
 
         Task { [weak webView] in
             if AppStateStore.shared.connectionMode == .local {

apps/macos/Sources/Clawdis/ClawdisConfigFile.swift

@@ -30,6 +30,23 @@ enum ClawdisConfigFile {
         } catch {}
     }
 
+    static func loadGatewayDict() -> [String: Any] {
+        let root = self.loadDict()
+        return root["gateway"] as? [String: Any] ?? [:]
+    }
+
+    static func updateGatewayDict(_ mutate: (inout [String: Any]) -> Void) {
+        var root = self.loadDict()
+        var gateway = root["gateway"] as? [String: Any] ?? [:]
+        mutate(&gateway)
+        if gateway.isEmpty {
+            root.removeValue(forKey: "gateway")
+        } else {
+            root["gateway"] = gateway
+        }
+        self.saveDict(root)
+    }
+
     static func browserControlEnabled(defaultValue: Bool = true) -> Bool {
         let root = self.loadDict()
         let browser = root["browser"] as? [String: Any]
@@ -62,28 +79,4 @@ enum ClawdisConfigFile {
         root["inbound"] = inbound
         self.saveDict(root)
     }
-
-    static func loadIdentity() -> AgentIdentity? {
-        let root = self.loadDict()
-        guard let identity = root["identity"] as? [String: Any] else { return nil }
-        let name = identity["name"] as? String ?? ""
-        let theme = identity["theme"] as? String ?? ""
-        let emoji = identity["emoji"] as? String ?? ""
-        let result = AgentIdentity(name: name, theme: theme, emoji: emoji)
-        return result.isEmpty ? nil : result
-    }
-
-    static func setIdentity(_ identity: AgentIdentity?) {
-        var root = self.loadDict()
-        if let identity, !identity.isEmpty {
-            root["identity"] = [
-                "name": identity.name.trimmingCharacters(in: .whitespacesAndNewlines),
-                "theme": identity.theme.trimmingCharacters(in: .whitespacesAndNewlines),
-                "emoji": identity.emoji.trimmingCharacters(in: .whitespacesAndNewlines),
-            ]
-        } else {
-            root.removeValue(forKey: "identity")
-        }
-        self.saveDict(root)
-    }
 }

apps/macos/Sources/Clawdis/ConnectionsSettings.swift

@@ -0,0 +1,350 @@
+import AppKit
+import SwiftUI
+
+struct ConnectionsSettings: View {
+    @Bindable var store: ConnectionsStore
+    @State private var showTelegramToken = false
+
+    init(store: ConnectionsStore = .shared) {
+        self.store = store
+    }
+
+    var body: some View {
+        ScrollView(.vertical) {
+            VStack(alignment: .leading, spacing: 14) {
+                self.header
+                self.whatsAppSection
+                self.telegramSection
+                Spacer(minLength: 0)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+            .padding(.horizontal, 24)
+            .padding(.vertical, 18)
+        }
+        .onAppear { self.store.start() }
+        .onDisappear { self.store.stop() }
+    }
+
+    private var header: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text("Connections")
+                .font(.title3.weight(.semibold))
+            Text("Link and monitor WhatsApp and Telegram providers.")
+                .font(.callout)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    private var whatsAppSection: some View {
+        GroupBox("WhatsApp") {
+            VStack(alignment: .leading, spacing: 10) {
+                self.providerHeader(
+                    title: "WhatsApp Web",
+                    color: self.whatsAppTint,
+                    subtitle: self.whatsAppSummary)
+
+                if let details = self.whatsAppDetails {
+                    Text(details)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if let message = self.store.whatsappLoginMessage {
+                    Text(message)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if let qr = self.store.whatsappLoginQrDataUrl, let image = self.qrImage(from: qr) {
+                    Image(nsImage: image)
+                        .resizable()
+                        .interpolation(.none)
+                        .frame(width: 180, height: 180)
+                        .cornerRadius(8)
+                }
+
+                HStack(spacing: 12) {
+                    Button {
+                        Task { await self.store.startWhatsAppLogin(force: false) }
+                    } label: {
+                        if self.store.whatsappBusy {
+                            ProgressView().controlSize(.small)
+                        } else {
+                            Text("Show QR")
+                        }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(self.store.whatsappBusy)
+
+                    Button("Relink") {
+                        Task { await self.store.startWhatsAppLogin(force: true) }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.whatsappBusy)
+
+                    Spacer()
+
+                    Button("Logout") {
+                        Task { await self.store.logoutWhatsApp() }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.whatsappBusy)
+
+                    Button("Refresh") {
+                        Task { await self.store.refresh(probe: true) }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.isRefreshing)
+                }
+                .font(.caption)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    private var telegramSection: some View {
+        GroupBox("Telegram") {
+            VStack(alignment: .leading, spacing: 10) {
+                self.providerHeader(
+                    title: "Telegram Bot",
+                    color: self.telegramTint,
+                    subtitle: self.telegramSummary)
+
+                if let details = self.telegramDetails {
+                    Text(details)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                if let status = self.store.configStatus {
+                    Text(status)
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                        .fixedSize(horizontal: false, vertical: true)
+                }
+
+                Divider().padding(.vertical, 2)
+
+                Grid(alignment: .leadingFirstTextBaseline, horizontalSpacing: 14, verticalSpacing: 10) {
+                    GridRow {
+                        self.gridLabel("Bot token")
+                        if self.showTelegramToken {
+                            TextField("123:abc", text: self.$store.telegramToken)
+                                .textFieldStyle(.roundedBorder)
+                                .disabled(self.isTelegramTokenLocked)
+                        } else {
+                            SecureField("123:abc", text: self.$store.telegramToken)
+                                .textFieldStyle(.roundedBorder)
+                                .disabled(self.isTelegramTokenLocked)
+                        }
+                        Toggle("Show", isOn: self.$showTelegramToken)
+                            .toggleStyle(.switch)
+                            .disabled(self.isTelegramTokenLocked)
+                    }
+                    GridRow {
+                        self.gridLabel("Require mention")
+                        Toggle("", isOn: self.$store.telegramRequireMention)
+                            .labelsHidden()
+                            .toggleStyle(.checkbox)
+                    }
+                    GridRow {
+                        self.gridLabel("Allow from")
+                        TextField("123456789, @team", text: self.$store.telegramAllowFrom)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Proxy")
+                        TextField("socks5://localhost:9050", text: self.$store.telegramProxy)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Webhook URL")
+                        TextField("https://example.com/telegram-webhook", text: self.$store.telegramWebhookUrl)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Webhook secret")
+                        TextField("secret", text: self.$store.telegramWebhookSecret)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                    GridRow {
+                        self.gridLabel("Webhook path")
+                        TextField("/telegram-webhook", text: self.$store.telegramWebhookPath)
+                            .textFieldStyle(.roundedBorder)
+                    }
+                }
+
+                if self.isTelegramTokenLocked {
+                    Text("Token set via TELEGRAM_BOT_TOKEN env; config edits won’t override it.")
+                        .font(.caption)
+                        .foregroundStyle(.secondary)
+                }
+
+                HStack(spacing: 12) {
+                    Button {
+                        Task { await self.store.saveTelegramConfig() }
+                    } label: {
+                        if self.store.isSavingConfig {
+                            ProgressView().controlSize(.small)
+                        } else {
+                            Text("Save")
+                        }
+                    }
+                    .buttonStyle(.borderedProminent)
+                    .disabled(self.store.isSavingConfig)
+
+                    Spacer()
+
+                    Button("Logout") {
+                        Task { await self.store.logoutTelegram() }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.telegramBusy)
+
+                    Button("Refresh") {
+                        Task { await self.store.refresh(probe: true) }
+                    }
+                    .buttonStyle(.bordered)
+                    .disabled(self.store.isRefreshing)
+                }
+                .font(.caption)
+            }
+            .frame(maxWidth: .infinity, alignment: .leading)
+        }
+    }
+
+    private var whatsAppTint: Color {
+        guard let status = self.store.snapshot?.whatsapp else { return .secondary }
+        if !status.linked { return .red }
+        if status.connected { return .green }
+        if status.lastError != nil { return .orange }
+        return .green
+    }
+
+    private var telegramTint: Color {
+        guard let status = self.store.snapshot?.telegram else { return .secondary }
+        if !status.configured { return .secondary }
+        if status.running { return .green }
+        if status.lastError != nil { return .orange }
+        return .secondary
+    }
+
+    private var whatsAppSummary: String {
+        guard let status = self.store.snapshot?.whatsapp else { return "Checking…" }
+        if !status.linked { return "Not linked" }
+        if status.connected { return "Connected" }
+        if status.running { return "Running" }
+        return "Linked"
+    }
+
+    private var telegramSummary: String {
+        guard let status = self.store.snapshot?.telegram else { return "Checking…" }
+        if !status.configured { return "Not configured" }
+        if status.running { return "Running" }
+        return "Configured"
+    }
+
+    private var whatsAppDetails: String? {
+        guard let status = self.store.snapshot?.whatsapp else { return nil }
+        var lines: [String] = []
+        if let e164 = status.`self`?.e164 ?? status.`self`?.jid {
+            lines.append("Linked as \(e164)")
+        }
+        if let age = status.authAgeMs {
+            lines.append("Auth age \(msToAge(age))")
+        }
+        if let last = self.date(fromMs: status.lastConnectedAt) {
+            lines.append("Last connect \(relativeAge(from: last))")
+        }
+        if let disconnect = status.lastDisconnect {
+            let when = self.date(fromMs: disconnect.at).map { relativeAge(from: $0) } ?? "unknown"
+            let code = disconnect.status.map { "status \($0)" } ?? "status unknown"
+            let err = disconnect.error ?? "disconnect"
+            lines.append("Last disconnect \(code) · \(err) · \(when)")
+        }
+        if status.reconnectAttempts > 0 {
+            lines.append("Reconnect attempts \(status.reconnectAttempts)")
+        }
+        if let msgAt = self.date(fromMs: status.lastMessageAt) {
+            lines.append("Last message \(relativeAge(from: msgAt))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    private var telegramDetails: String? {
+        guard let status = self.store.snapshot?.telegram else { return nil }
+        var lines: [String] = []
+        if let source = status.tokenSource {
+            lines.append("Token source: \(source)")
+        }
+        if let mode = status.mode {
+            lines.append("Mode: \(mode)")
+        }
+        if let probe = status.probe {
+            if probe.ok {
+                if let name = probe.bot?.username {
+                    lines.append("Bot: @\(name)")
+                }
+                if let url = probe.webhook?.url, !url.isEmpty {
+                    lines.append("Webhook: \(url)")
+                }
+            } else {
+                let code = probe.status.map { String($0) } ?? "unknown"
+                lines.append("Probe failed (\(code))")
+            }
+        }
+        if let last = self.date(fromMs: status.lastProbeAt) {
+            lines.append("Last probe \(relativeAge(from: last))")
+        }
+        if let err = status.lastError, !err.isEmpty {
+            lines.append("Error: \(err)")
+        }
+        return lines.isEmpty ? nil : lines.joined(separator: " · ")
+    }
+
+    private var isTelegramTokenLocked: Bool {
+        self.store.snapshot?.telegram.tokenSource == "env"
+    }
+
+    private func providerHeader(title: String, color: Color, subtitle: String) -> some View {
+        HStack(spacing: 10) {
+            Circle()
+                .fill(color)
+                .frame(width: 10, height: 10)
+            VStack(alignment: .leading, spacing: 2) {
+                Text(title)
+                    .font(.headline)
+                Text(subtitle)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+            Spacer()
+        }
+    }
+
+    private func gridLabel(_ text: String) -> some View {
+        Text(text)
+            .font(.callout.weight(.semibold))
+            .frame(width: 120, alignment: .leading)
+    }
+
+    private func date(fromMs ms: Double?) -> Date? {
+        guard let ms else { return nil }
+        return Date(timeIntervalSince1970: ms / 1000)
+    }
+
+    private func qrImage(from dataUrl: String) -> NSImage? {
+        guard let comma = dataUrl.firstIndex(of: ",") else { return nil }
+        let header = dataUrl[..<comma]
+        guard header.contains("base64") else { return nil }
+        let base64 = dataUrl[dataUrl.index(after: comma)...]
+        guard let data = Data(base64Encoded: String(base64)) else { return nil }
+        return NSImage(data: data)
+    }
+}

apps/macos/Sources/Clawdis/ConnectionsStore.swift

@@ -0,0 +1,393 @@
+import ClawdisProtocol
+import Foundation
+import Observation
+
+struct ProvidersStatusSnapshot: Codable {
+    struct WhatsAppSelf: Codable {
+        let e164: String?
+        let jid: String?
+    }
+
+    struct WhatsAppDisconnect: Codable {
+        let at: Double
+        let status: Int?
+        let error: String?
+        let loggedOut: Bool?
+    }
+
+    struct WhatsAppStatus: Codable {
+        let configured: Bool
+        let linked: Bool
+        let authAgeMs: Double?
+        let `self`: WhatsAppSelf?
+        let running: Bool
+        let connected: Bool
+        let lastConnectedAt: Double?
+        let lastDisconnect: WhatsAppDisconnect?
+        let reconnectAttempts: Int
+        let lastMessageAt: Double?
+        let lastEventAt: Double?
+        let lastError: String?
+    }
+
+    struct TelegramBot: Codable {
+        let id: Int?
+        let username: String?
+    }
+
+    struct TelegramWebhook: Codable {
+        let url: String?
+        let hasCustomCert: Bool?
+    }
+
+    struct TelegramProbe: Codable {
+        let ok: Bool
+        let status: Int?
+        let error: String?
+        let elapsedMs: Double?
+        let bot: TelegramBot?
+        let webhook: TelegramWebhook?
+    }
+
+    struct TelegramStatus: Codable {
+        let configured: Bool
+        let tokenSource: String?
+        let running: Bool
+        let mode: String?
+        let lastStartAt: Double?
+        let lastStopAt: Double?
+        let lastError: String?
+        let probe: TelegramProbe?
+        let lastProbeAt: Double?
+    }
+
+    let ts: Double
+    let whatsapp: WhatsAppStatus
+    let telegram: TelegramStatus
+}
+
+struct ConfigSnapshot: Codable {
+    struct Issue: Codable {
+        let path: String
+        let message: String
+    }
+
+    let path: String?
+    let exists: Bool?
+    let raw: String?
+    let parsed: AnyCodable?
+    let valid: Bool?
+    let config: [String: AnyCodable]?
+    let issues: [Issue]?
+}
+
+@MainActor
+@Observable
+final class ConnectionsStore {
+    static let shared = ConnectionsStore()
+
+    var snapshot: ProvidersStatusSnapshot?
+    var lastError: String?
+    var lastSuccess: Date?
+    var isRefreshing = false
+
+    var whatsappLoginMessage: String?
+    var whatsappLoginQrDataUrl: String?
+    var whatsappLoginConnected: Bool?
+    var whatsappBusy = false
+
+    var telegramToken: String = ""
+    var telegramRequireMention = true
+    var telegramAllowFrom: String = ""
+    var telegramProxy: String = ""
+    var telegramWebhookUrl: String = ""
+    var telegramWebhookSecret: String = ""
+    var telegramWebhookPath: String = ""
+    var telegramBusy = false
+    var configStatus: String?
+    var isSavingConfig = false
+
+    private let interval: TimeInterval = 45
+    private let isPreview: Bool
+    private var pollTask: Task<Void, Never>?
+    private var configRoot: [String: Any] = [:]
+    private var configLoaded = false
+
+    init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
+        self.isPreview = isPreview
+    }
+
+    func start() {
+        guard !self.isPreview else { return }
+        guard self.pollTask == nil else { return }
+        self.pollTask = Task.detached { [weak self] in
+            guard let self else { return }
+            await self.refresh(probe: true)
+            await self.loadConfig()
+            while !Task.isCancelled {
+                try? await Task.sleep(nanoseconds: UInt64(self.interval * 1_000_000_000))
+                await self.refresh(probe: false)
+            }
+        }
+    }
+
+    func stop() {
+        self.pollTask?.cancel()
+        self.pollTask = nil
+    }
+
+    func refresh(probe: Bool) async {
+        guard !self.isRefreshing else { return }
+        self.isRefreshing = true
+        defer { self.isRefreshing = false }
+
+        do {
+            let params: [String: AnyCodable] = [
+                "probe": AnyCodable(probe),
+                "timeoutMs": AnyCodable(8000),
+            ]
+            let snap: ProvidersStatusSnapshot = try await GatewayConnection.shared.requestDecoded(
+                method: .providersStatus,
+                params: params,
+                timeoutMs: 12000)
+            self.snapshot = snap
+            self.lastSuccess = Date()
+            self.lastError = nil
+        } catch {
+            self.lastError = error.localizedDescription
+        }
+    }
+
+    func startWhatsAppLogin(force: Bool, autoWait: Bool = true) async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        var shouldAutoWait = false
+        do {
+            let params: [String: AnyCodable] = [
+                "force": AnyCodable(force),
+                "timeoutMs": AnyCodable(30000),
+            ]
+            let result: WhatsAppLoginStartResult = try await GatewayConnection.shared.requestDecoded(
+                method: .webLoginStart,
+                params: params,
+                timeoutMs: 35000)
+            self.whatsappLoginMessage = result.message
+            self.whatsappLoginQrDataUrl = result.qrDataUrl
+            self.whatsappLoginConnected = nil
+            shouldAutoWait = autoWait && result.qrDataUrl != nil
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+            self.whatsappLoginQrDataUrl = nil
+            self.whatsappLoginConnected = nil
+        }
+        await self.refresh(probe: true)
+        if shouldAutoWait {
+            Task { await self.waitWhatsAppLogin() }
+        }
+    }
+
+    func waitWhatsAppLogin(timeoutMs: Int = 120_000) async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        do {
+            let params: [String: AnyCodable] = [
+                "timeoutMs": AnyCodable(timeoutMs),
+            ]
+            let result: WhatsAppLoginWaitResult = try await GatewayConnection.shared.requestDecoded(
+                method: .webLoginWait,
+                params: params,
+                timeoutMs: Double(timeoutMs) + 5000)
+            self.whatsappLoginMessage = result.message
+            self.whatsappLoginConnected = result.connected
+            if result.connected {
+                self.whatsappLoginQrDataUrl = nil
+            }
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+
+    func logoutWhatsApp() async {
+        guard !self.whatsappBusy else { return }
+        self.whatsappBusy = true
+        defer { self.whatsappBusy = false }
+        do {
+            let result: WhatsAppLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .webLogout,
+                params: nil,
+                timeoutMs: 15000)
+            self.whatsappLoginMessage = result.cleared
+                ? "Logged out and cleared credentials."
+                : "No WhatsApp session found."
+            self.whatsappLoginQrDataUrl = nil
+        } catch {
+            self.whatsappLoginMessage = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+
+    func logoutTelegram() async {
+        guard !self.telegramBusy else { return }
+        self.telegramBusy = true
+        defer { self.telegramBusy = false }
+        do {
+            let result: TelegramLogoutResult = try await GatewayConnection.shared.requestDecoded(
+                method: .telegramLogout,
+                params: nil,
+                timeoutMs: 15000)
+            if result.envToken == true {
+                self.configStatus = "Telegram token still set via env; config cleared."
+            } else {
+                self.configStatus = result.cleared
+                    ? "Telegram token cleared."
+                    : "No Telegram token configured."
+            }
+            await self.loadConfig()
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+        await self.refresh(probe: true)
+    }
+
+    func loadConfig() async {
+        do {
+            let snap: ConfigSnapshot = try await GatewayConnection.shared.requestDecoded(
+                method: .configGet,
+                params: nil,
+                timeoutMs: 10000)
+            self.configStatus = snap.valid == false
+                ? "Config invalid; fix it in ~/.clawdis/clawdis.json."
+                : nil
+            self.configRoot = snap.config?.mapValues { $0.foundationValue } ?? [:]
+            self.configLoaded = true
+            let telegram = snap.config?["telegram"]?.dictionaryValue
+            self.telegramToken = telegram?["botToken"]?.stringValue ?? ""
+            self.telegramRequireMention = telegram?["requireMention"]?.boolValue ?? true
+            if let allow = telegram?["allowFrom"]?.arrayValue {
+                let strings = allow.compactMap { entry -> String? in
+                    if let str = entry.stringValue { return str }
+                    if let intVal = entry.intValue { return String(intVal) }
+                    if let doubleVal = entry.doubleValue { return String(Int(doubleVal)) }
+                    return nil
+                }
+                self.telegramAllowFrom = strings.joined(separator: ", ")
+            } else {
+                self.telegramAllowFrom = ""
+            }
+            self.telegramProxy = telegram?["proxy"]?.stringValue ?? ""
+            self.telegramWebhookUrl = telegram?["webhookUrl"]?.stringValue ?? ""
+            self.telegramWebhookSecret = telegram?["webhookSecret"]?.stringValue ?? ""
+            self.telegramWebhookPath = telegram?["webhookPath"]?.stringValue ?? ""
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+    }
+
+    func saveTelegramConfig() async {
+        guard !self.isSavingConfig else { return }
+        self.isSavingConfig = true
+        defer { self.isSavingConfig = false }
+        if !self.configLoaded {
+            await self.loadConfig()
+        }
+
+        var telegram: [String: Any] = (self.configRoot["telegram"] as? [String: Any]) ?? [:]
+        let token = self.telegramToken.trimmingCharacters(in: .whitespacesAndNewlines)
+        if token.isEmpty {
+            telegram.removeValue(forKey: "botToken")
+        } else {
+            telegram["botToken"] = token
+        }
+
+        if self.telegramRequireMention {
+            telegram["requireMention"] = true
+        } else {
+            telegram["requireMention"] = false
+        }
+
+        let allow = self.telegramAllowFrom
+            .split(separator: ",")
+            .map { $0.trimmingCharacters(in: .whitespacesAndNewlines) }
+            .filter { !$0.isEmpty }
+        if allow.isEmpty {
+            telegram.removeValue(forKey: "allowFrom")
+        } else {
+            telegram["allowFrom"] = allow
+        }
+
+        let proxy = self.telegramProxy.trimmingCharacters(in: .whitespacesAndNewlines)
+        if proxy.isEmpty {
+            telegram.removeValue(forKey: "proxy")
+        } else {
+            telegram["proxy"] = proxy
+        }
+
+        let webhookUrl = self.telegramWebhookUrl.trimmingCharacters(in: .whitespacesAndNewlines)
+        if webhookUrl.isEmpty {
+            telegram.removeValue(forKey: "webhookUrl")
+        } else {
+            telegram["webhookUrl"] = webhookUrl
+        }
+
+        let webhookSecret = self.telegramWebhookSecret.trimmingCharacters(in: .whitespacesAndNewlines)
+        if webhookSecret.isEmpty {
+            telegram.removeValue(forKey: "webhookSecret")
+        } else {
+            telegram["webhookSecret"] = webhookSecret
+        }
+
+        let webhookPath = self.telegramWebhookPath.trimmingCharacters(in: .whitespacesAndNewlines)
+        if webhookPath.isEmpty {
+            telegram.removeValue(forKey: "webhookPath")
+        } else {
+            telegram["webhookPath"] = webhookPath
+        }
+
+        if telegram.isEmpty {
+            self.configRoot.removeValue(forKey: "telegram")
+        } else {
+            self.configRoot["telegram"] = telegram
+        }
+
+        do {
+            let data = try JSONSerialization.data(
+                withJSONObject: self.configRoot,
+                options: [.prettyPrinted, .sortedKeys])
+            guard let raw = String(data: data, encoding: .utf8) else {
+                self.configStatus = "Failed to encode config."
+                return
+            }
+            let params: [String: AnyCodable] = ["raw": AnyCodable(raw)]
+            _ = try await GatewayConnection.shared.requestRaw(
+                method: .configSet,
+                params: params,
+                timeoutMs: 10000)
+            self.configStatus = "Saved to ~/.clawdis/clawdis.json."
+            await self.refresh(probe: true)
+        } catch {
+            self.configStatus = error.localizedDescription
+        }
+    }
+}
+
+private struct WhatsAppLoginStartResult: Codable {
+    let qrDataUrl: String?
+    let message: String
+}
+
+private struct WhatsAppLoginWaitResult: Codable {
+    let connected: Bool
+    let message: String
+}
+
+private struct WhatsAppLogoutResult: Codable {
+    let cleared: Bool
+}
+
+private struct TelegramLogoutResult: Codable {
+    let cleared: Bool
+    let envToken: Bool?
+}

apps/macos/Sources/Clawdis/GatewayConnection.swift

@@ -109,24 +109,61 @@ actor GatewayConnection {
         do {
             return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
         } catch {
+            if error is GatewayResponseError || error is GatewayDecodingError {
+                throw error
+            }
+
             // Auto-recover in local mode by spawning/attaching a gateway and retrying a few times.
             // Canvas interactions should "just work" even if the local gateway isn't running yet.
-            let isLocal = await MainActor.run { AppStateStore.shared.connectionMode == .local }
-            guard isLocal else { throw error }
+            let mode = await MainActor.run { AppStateStore.shared.connectionMode }
+            switch mode {
+            case .local:
+                await MainActor.run { GatewayProcessManager.shared.setActive(true) }
 
-            await MainActor.run { GatewayProcessManager.shared.setActive(true) }
+                var lastError: Error = error
+                for delayMs in [150, 400, 900] {
+                    try await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+                    do {
+                        return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
+                    } catch {
+                        lastError = error
+                    }
+                }
 
-            var lastError: Error = error
-            for delayMs in [150, 400, 900] {
-                try await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+                throw lastError
+            case .remote:
+                let nsError = error as NSError
+                guard nsError.domain == URLError.errorDomain else { throw error }
+
+                var lastError: Error = error
+                await RemoteTunnelManager.shared.stopAll()
                 do {
-                    return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
+                    _ = try await GatewayEndpointStore.shared.ensureRemoteControlTunnel()
                 } catch {
                     lastError = error
                 }
-            }
 
-            throw lastError
+                for delayMs in [150, 400, 900] {
+                    try await Task.sleep(nanoseconds: UInt64(delayMs) * 1_000_000)
+                    do {
+                        let cfg = try await self.configProvider()
+                        await self.configure(url: cfg.url, token: cfg.token)
+                        guard let client = self.client else {
+                            throw NSError(
+                                domain: "Gateway",
+                                code: 0,
+                                userInfo: [NSLocalizedDescriptionKey: "gateway not configured"])
+                        }
+                        return try await client.request(method: method, params: params, timeoutMs: timeoutMs)
+                    } catch {
+                        lastError = error
+                    }
+                }
+
+                throw lastError
+            case .unconfigured:
+                throw error
+            }
         }
     }
 

apps/macos/Sources/Clawdis/GatewayDiscoveryModel.swift

@@ -327,10 +327,8 @@ final class GatewayDiscoveryModel {
             return true
         }
         if let service = normalizeServiceToken(serviceName) {
-            for token in local.hostTokens {
-                if service.contains(token) {
-                    return true
-                }
+            for token in local.hostTokens where service.contains(token) {
+                return true
             }
         }
         return false
@@ -456,8 +454,9 @@ final class GatewayTXTResolver: NSObject, NetServiceDelegate {
     func netServiceDidResolveAddress(_ sender: NetService) {
         let txt = Self.decodeTXT(sender.txtRecordData())
         if !txt.isEmpty {
+            let payload = self.formatTXT(txt)
             self.logger.debug(
-                "discovery: resolved TXT for \(sender.name, privacy: .public): \(self.formatTXT(txt), privacy: .public)")
+                "discovery: resolved TXT for \(sender.name, privacy: .public): \(payload, privacy: .public)")
         }
         self.finish(result: .success(txt))
     }

apps/macos/Sources/Clawdis/GeneralSettings.swift

@@ -126,12 +126,17 @@ struct GeneralSettings: View {
 
             if self.state.connectionMode == .local {
                 self.gatewayInstallerCard
+                TailscaleIntegrationSection(
+                    connectionMode: self.state.connectionMode,
+                    isPaused: self.state.isPaused)
                 self.healthRow
             }
 
             if self.state.connectionMode == .remote {
                 self.remoteCard
             }
+
+            self.cliInstaller
         }
     }
 
@@ -583,7 +588,8 @@ extension GeneralSettings {
            trimmed.localizedCaseInsensitiveContains("host key verification failed")
         {
             let host = CommandResolver.parseSSHTarget(target)?.host ?? target
-            return "SSH check failed: Host key verification failed. Remove the old key with `ssh-keygen -R \(host)` and try again."
+            return "SSH check failed: Host key verification failed. Remove the old key with " +
+                "`ssh-keygen -R \(host)` and try again."
         }
         if let trimmed, !trimmed.isEmpty {
             if let message = response.message, message.hasPrefix("exit ") {
@@ -642,6 +648,7 @@ struct GeneralSettings_Previews: PreviewProvider {
     static var previews: some View {
         GeneralSettings(state: .preview)
             .frame(width: SettingsTab.windowWidth, height: SettingsTab.windowHeight)
+            .environment(TailscaleService.shared)
     }
 }
 #endif

apps/macos/Sources/Clawdis/MenuBar.swift

@@ -16,6 +16,7 @@ struct ClawdisApp: App {
     @State private var isMenuPresented = false
     @State private var isPanelVisible = false
     @State private var menuInjector = MenuContextCardInjector.shared
+    @State private var tailscaleService = TailscaleService.shared
 
     @MainActor
     private func updateStatusHighlight() {
@@ -66,6 +67,7 @@ struct ClawdisApp: App {
         Settings {
             SettingsRootView(state: self.state, updater: self.delegate.updaterController)
                 .frame(width: SettingsTab.windowWidth, height: SettingsTab.windowHeight, alignment: .topLeading)
+                .environment(self.tailscaleService)
         }
         .defaultSize(width: SettingsTab.windowWidth, height: SettingsTab.windowHeight)
         .windowResizability(.contentSize)

apps/macos/Sources/Clawdis/MenuContextCardInjector.swift

@@ -48,6 +48,7 @@ final class MenuContextCardInjector: NSObject, NSMenuDelegate {
         let initialRows = self.cachedRows
         let initialIsLoading = initialRows.isEmpty
         let initialStatusText = initialIsLoading ? self.cacheErrorText : nil
+        let initialWidth = self.initialCardWidth(for: menu)
 
         let initial = AnyView(ContextMenuCardView(
             rows: initialRows,
@@ -55,8 +56,8 @@ final class MenuContextCardInjector: NSObject, NSMenuDelegate {
             isLoading: initialIsLoading))
 
         let hosting = NSHostingView(rootView: initial)
+        hosting.frame.size.width = max(1, initialWidth)
         let size = hosting.fittingSize
-        let initialWidth = self.initialCardWidth(for: menu)
         hosting.frame = NSRect(
             origin: .zero,
             size: NSSize(width: initialWidth, height: size.height))
@@ -83,6 +84,7 @@ final class MenuContextCardInjector: NSObject, NSMenuDelegate {
                     hosting.rootView = view
                     hosting.invalidateIntrinsicContentSize()
                     self.captureMenuWidthIfAvailable(for: menu, hosting: hosting)
+                    hosting.frame.size.width = max(1, initialWidth)
                     let size = hosting.fittingSize
                     hosting.frame.size.height = size.height
                 }

apps/macos/Sources/Clawdis/NodeMode/MacNodeRuntime.swift

@@ -7,7 +7,7 @@ actor MacNodeRuntime {
     private let cameraCapture = CameraCaptureService()
     @MainActor private let screenRecorder = ScreenRecordService()
 
-    // swiftlint:disable:next function_body_length
+    // swiftlint:disable:next function_body_length cyclomatic_complexity
     func handleInvoke(_ req: BridgeInvokeRequest) async -> BridgeInvokeResponse {
         let command = req.command
         if command.hasPrefix("canvas.") || command.hasPrefix("canvas.a2ui."), !Self.canvasEnabled() {

apps/macos/Sources/Clawdis/Onboarding.swift

@@ -24,7 +24,7 @@ final class OnboardingController {
         let hosting = NSHostingController(rootView: OnboardingView())
         let window = NSWindow(contentViewController: hosting)
         window.title = UIStrings.welcomeTitle
-        window.setContentSize(NSSize(width: 680, height: 840))
+        window.setContentSize(NSSize(width: 630, height: 644))
         window.styleMask = [.titled, .closable, .fullSizeContentView]
         window.titlebarAppearsTransparent = true
         window.titleVisibility = .hidden
@@ -68,12 +68,7 @@ struct OnboardingView: View {
     @State private var anthropicAuthLastPasteboardChangeCount = NSPasteboard.general.changeCount
     @State private var monitoringAuth = false
     @State private var authMonitorTask: Task<Void, Never>?
-    @State private var identityName: String = ""
-    @State private var identityTheme: String = ""
-    @State private var identityEmoji: String = ""
-    @State private var identityStatus: String?
-    @State private var identityApplying = false
-    @State private var hasIdentity = false
+    @State private var needsBootstrap = false
     @State private var didAutoKickoff = false
     @State private var showAdvancedConnection = false
     @State private var preferredGatewayID: String?
@@ -83,8 +78,8 @@ struct OnboardingView: View {
     @Bindable private var state: AppState
     private var permissionMonitor: PermissionMonitor
 
-    private let pageWidth: CGFloat = 680
-    private let contentHeight: CGFloat = 520
+    private let pageWidth: CGFloat = 630
+    private let contentHeight: CGFloat = 420
     private let connectionPageIndex = 1
     private let anthropicAuthPageIndex = 2
     private let onboardingChatPageIndex = 8
@@ -93,22 +88,22 @@ struct OnboardingView: View {
     private let permissionsPageIndex = 5
     static func pageOrder(
         for mode: AppState.ConnectionMode,
-        hasIdentity: Bool) -> [Int]
+        needsBootstrap: Bool) -> [Int]
     {
         switch mode {
         case .remote:
             // Remote setup doesn't need local gateway/CLI/workspace setup pages,
             // and WhatsApp/Telegram setup is optional.
-            hasIdentity ? [0, 1, 5, 9] : [0, 1, 5, 8, 9]
+            needsBootstrap ? [0, 1, 5, 8, 9] : [0, 1, 5, 9]
         case .unconfigured:
-            hasIdentity ? [0, 1, 9] : [0, 1, 8, 9]
+            needsBootstrap ? [0, 1, 8, 9] : [0, 1, 9]
         case .local:
-            hasIdentity ? [0, 1, 2, 5, 6, 9] : [0, 1, 2, 5, 6, 8, 9]
+            needsBootstrap ? [0, 1, 2, 5, 6, 8, 9] : [0, 1, 2, 5, 6, 9]
         }
     }
 
     private var pageOrder: [Int] {
-        Self.pageOrder(for: self.state.connectionMode, hasIdentity: self.hasIdentity)
+        Self.pageOrder(for: self.state.connectionMode, needsBootstrap: self.needsBootstrap)
     }
 
     private var pageCount: Int { self.pageOrder.count }
@@ -145,9 +140,9 @@ struct OnboardingView: View {
 
     var body: some View {
         VStack(spacing: 0) {
-            GlowingClawdisIcon(size: 156, glowIntensity: 0.28)
-                .offset(y: 13)
-                .frame(height: 181)
+            GlowingClawdisIcon(size: 130, glowIntensity: 0.28)
+                .offset(y: 10)
+                .frame(height: 145)
 
             GeometryReader { _ in
                 HStack(spacing: 0) {
@@ -165,9 +160,10 @@ struct OnboardingView: View {
             }
             .frame(height: self.contentHeight)
 
+            Spacer(minLength: 0)
             self.navigationBar
         }
-        .frame(width: self.pageWidth, height: 840)
+        .frame(width: self.pageWidth, height: 644)
         .background(Color(NSColor.windowBackgroundColor))
         .onAppear {
             self.currentPage = 0
@@ -181,7 +177,7 @@ struct OnboardingView: View {
             self.reconcilePageForModeChange(previousActivePageIndex: oldActive)
             self.updateDiscoveryMonitoring(for: self.activePageIndex)
         }
-        .onChange(of: self.hasIdentity) { _, _ in
+        .onChange(of: self.needsBootstrap) { _, _ in
             if self.currentPage >= self.pageOrder.count {
                 self.currentPage = max(0, self.pageOrder.count - 1)
             }
@@ -197,7 +193,7 @@ struct OnboardingView: View {
             self.loadWorkspaceDefaults()
             self.ensureDefaultWorkspace()
             self.refreshAnthropicOAuthStatus()
-            self.loadIdentityDefaults()
+            self.refreshBootstrapStatus()
             self.preferredGatewayID = BridgeDiscoveryPreferences.preferredStableID()
         }
     }
@@ -229,8 +225,6 @@ struct OnboardingView: View {
             self.connectionPage()
         case 2:
             self.anthropicAuthPage()
-        case 3:
-            self.identityPage()
         case 5:
             self.permissionsPage()
         case 6:
@@ -249,9 +243,7 @@ struct OnboardingView: View {
             VStack(spacing: 22) {
                 Text("Welcome to Clawdis")
                     .font(.largeTitle.weight(.semibold))
-                Text(
-                    "Your macOS menu bar companion for notifications, screenshots, and agent automation. " +
-                        "Setup takes a few minutes.")
+                Text("Clawdis is a powerful personal AI assistant that can connect to WhatsApp or Telegram.")
                     .font(.body)
                     .foregroundStyle(.secondary)
                     .multilineTextAlignment(.center)
@@ -730,99 +722,6 @@ struct OnboardingView: View {
         self.anthropicAuthConnected = status.isConnected
     }
 
-    private func identityPage() -> some View {
-        self.onboardingPage {
-            Text("Identity")
-                .font(.largeTitle.weight(.semibold))
-            Text("Name your agent, pick a vibe, and choose an emoji.")
-                .font(.body)
-                .foregroundStyle(.secondary)
-                .multilineTextAlignment(.center)
-                .frame(maxWidth: 520)
-                .fixedSize(horizontal: false, vertical: true)
-
-            self.onboardingCard(spacing: 12, padding: 16) {
-                VStack(alignment: .leading, spacing: 10) {
-                    Text("Agent name")
-                        .font(.headline)
-                    TextField("Clawd", text: self.$identityName)
-                        .textFieldStyle(.roundedBorder)
-                }
-
-                VStack(alignment: .leading, spacing: 10) {
-                    Text("Theme")
-                        .font(.headline)
-                    TextField("helpful space lobster", text: self.$identityTheme)
-                        .textFieldStyle(.roundedBorder)
-                }
-
-                VStack(alignment: .leading, spacing: 10) {
-                    Text("Emoji")
-                        .font(.headline)
-                    HStack(spacing: 12) {
-                        TextField("🦞", text: self.$identityEmoji)
-                            .textFieldStyle(.roundedBorder)
-                            .frame(width: 120)
-
-                        Button("Suggest") {
-                            let suggested = AgentIdentityEmoji.suggest(theme: self.identityTheme)
-                            self.identityEmoji = suggested
-                        }
-                        .buttonStyle(.bordered)
-                    }
-                }
-
-                Divider().padding(.vertical, 2)
-
-                VStack(alignment: .leading, spacing: 8) {
-                    Text("Workspace")
-                        .font(.headline)
-                    Text(self.workspacePath.isEmpty ? AgentWorkspace
-                        .displayPath(for: ClawdisConfigFile.defaultWorkspaceURL()) : self.workspacePath)
-                        .font(.callout)
-                        .foregroundStyle(.secondary)
-                }
-
-                HStack(spacing: 12) {
-                    Button {
-                        Task { await self.applyIdentity() }
-                    } label: {
-                        if self.identityApplying {
-                            ProgressView()
-                        } else {
-                            Text("Save identity")
-                        }
-                    }
-                    .buttonStyle(.borderedProminent)
-                    .disabled(self.identityApplying || self.identityName.trimmingCharacters(in: .whitespacesAndNewlines)
-                        .isEmpty)
-
-                    Button("Open workspace") {
-                        let url = AgentWorkspace.resolveWorkspaceURL(from: self.workspacePath)
-                        NSWorkspace.shared.open(url)
-                    }
-                    .buttonStyle(.bordered)
-                    .disabled(self.identityApplying)
-                }
-
-                Text(
-                    "This writes your identity to `~/.clawdis/clawdis.json` and into `AGENTS.md` " +
-                        "inside the workspace. " +
-                        "Treat that workspace as the agent’s “memory” and consider making it a private git repo.")
-                    .font(.caption)
-                    .foregroundStyle(.secondary)
-                    .fixedSize(horizontal: false, vertical: true)
-
-                if let status = self.identityStatus {
-                    Text(status)
-                        .font(.caption)
-                        .foregroundStyle(.secondary)
-                        .fixedSize(horizontal: false, vertical: true)
-                }
-            }
-        }
-    }
-
     private func permissionsPage() -> some View {
         self.onboardingPage {
             Text("Grant permissions")
@@ -834,9 +733,13 @@ struct OnboardingView: View {
                 .frame(maxWidth: 520)
                 .fixedSize(horizontal: false, vertical: true)
 
-            self.onboardingCard {
+            self.onboardingCard(spacing: 8, padding: 12) {
                 ForEach(Capability.allCases, id: \.self) { cap in
-                    PermissionRow(capability: cap, status: self.permissionMonitor.status[cap] ?? false) {
+                    PermissionRow(
+                        capability: cap,
+                        status: self.permissionMonitor.status[cap] ?? false,
+                        compact: true)
+                    {
                         Task { await self.request(cap) }
                     }
                 }
@@ -1005,7 +908,7 @@ struct OnboardingView: View {
     }
 
     private func onboardingChatPage() -> some View {
-        self.onboardingPage {
+        VStack(spacing: 16) {
             Text("Meet your agent")
                 .font(.largeTitle.weight(.semibold))
             Text(
@@ -1019,9 +922,12 @@ struct OnboardingView: View {
 
             self.onboardingCard(padding: 8) {
                 ClawdisChatView(viewModel: self.onboardingChatModel, style: .onboarding)
-                    .frame(height: 420)
+                    .frame(maxHeight: .infinity)
             }
+            .frame(maxHeight: .infinity)
         }
+        .padding(.horizontal, 28)
+        .frame(width: self.pageWidth, height: self.contentHeight, alignment: .top)
     }
 
     private func readyPage() -> some View {
@@ -1052,6 +958,13 @@ struct OnboardingView: View {
                     title: "Open the menu bar panel",
                     subtitle: "Click the Clawdis menu bar icon for quick chat and status.",
                     systemImage: "bubble.left.and.bubble.right")
+                self.featureActionRow(
+                    title: "Connect WhatsApp or Telegram",
+                    subtitle: "Open Settings → Connections to link providers and monitor status.",
+                    systemImage: "link")
+                {
+                    self.openSettings(tab: .connections)
+                }
                 self.featureRow(
                     title: "Try Voice Wake",
                     subtitle: "Enable Voice Wake in Settings for hands-free commands with a live transcript overlay.",
@@ -1061,10 +974,6 @@ struct OnboardingView: View {
                     subtitle: "Open the menu bar panel for quick chat; the agent can show previews " +
                         "and richer visuals in Canvas.",
                     systemImage: "rectangle.inset.filled.and.person.filled")
-                self.featureRow(
-                    title: "Test a notification",
-                    subtitle: "Send a quick notify via the menu bar to confirm sounds and permissions.",
-                    systemImage: "bell.badge")
                 self.featureActionRow(
                     title: "Give your agent more powers",
                     subtitle: "Enable optional skills (Peekaboo, oracle, camsnap, …) from Settings → Skills.",
@@ -1134,12 +1043,12 @@ struct OnboardingView: View {
             .buttonStyle(.borderedProminent)
         }
         .padding(.horizontal, 28)
-        .padding(.bottom, 36)
-        .frame(minHeight: 60)
+        .padding(.bottom, 13)
+        .frame(minHeight: 60, alignment: .bottom)
     }
 
     private func onboardingPage(@ViewBuilder _ content: () -> some View) -> some View {
-        VStack(spacing: 22) {
+        VStack(spacing: 16) {
             content()
             Spacer()
         }
@@ -1176,6 +1085,7 @@ struct OnboardingView: View {
                     .foregroundStyle(.secondary)
             }
         }
+        .padding(.vertical, 4)
     }
 
     private func featureActionRow(
@@ -1200,6 +1110,7 @@ struct OnboardingView: View {
             }
             Spacer(minLength: 0)
         }
+        .padding(.vertical, 4)
     }
 
     private func handleBack() {
@@ -1359,40 +1270,34 @@ struct OnboardingView: View {
         let configured = ClawdisConfigFile.inboundWorkspace()
         let url = AgentWorkspace.resolveWorkspaceURL(from: configured)
         self.workspacePath = AgentWorkspace.displayPath(for: url)
+        self.refreshBootstrapStatus()
     }
 
     private func ensureDefaultWorkspace() {
         guard self.state.connectionMode == .local else { return }
         let configured = ClawdisConfigFile.inboundWorkspace()
         let url = AgentWorkspace.resolveWorkspaceURL(from: configured)
-        do {
-            _ = try AgentWorkspace.bootstrap(workspaceURL: url)
-            if (configured ?? "").trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-                ClawdisConfigFile.setInboundWorkspace(AgentWorkspace.displayPath(for: url))
+        switch AgentWorkspace.bootstrapSafety(for: url) {
+        case .safe:
+            do {
+                _ = try AgentWorkspace.bootstrap(workspaceURL: url)
+                if (configured ?? "").trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
+                    ClawdisConfigFile.setInboundWorkspace(AgentWorkspace.displayPath(for: url))
+                }
+            } catch {
+                self.workspaceStatus = "Failed to create workspace: \(error.localizedDescription)"
             }
-        } catch {
-            self.workspaceStatus = "Failed to create workspace: \(error.localizedDescription)"
+        case let .unsafe(reason):
+            self.workspaceStatus = "Workspace not touched: \(reason)"
         }
+        self.refreshBootstrapStatus()
     }
 
-    private func loadIdentityDefaults() {
-        if let identity = ClawdisConfigFile.loadIdentity() {
-            self.identityName = identity.name
-            self.identityTheme = identity.theme
-            self.identityEmoji = identity.emoji
-            self.hasIdentity = !identity.isEmpty
-            return
-        }
-
-        self.hasIdentity = false
-        if self.identityName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            self.identityName = "Clawd"
-        }
-        if self.identityTheme.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            self.identityTheme = "helpful space lobster"
-        }
-        if self.identityEmoji.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            self.identityEmoji = AgentIdentityEmoji.suggest(theme: self.identityTheme)
+    private func refreshBootstrapStatus() {
+        let url = AgentWorkspace.resolveWorkspaceURL(from: self.workspacePath)
+        self.needsBootstrap = AgentWorkspace.needsBootstrap(workspaceURL: url)
+        if self.needsBootstrap {
+            self.didAutoKickoff = false
         }
     }
 
@@ -1413,48 +1318,22 @@ struct OnboardingView: View {
 
         do {
             let url = AgentWorkspace.resolveWorkspaceURL(from: self.workspacePath)
+            if case let .unsafe(reason) = AgentWorkspace.bootstrapSafety(for: url) {
+                self.workspaceStatus = "Workspace not created: \(reason)"
+                return
+            }
             _ = try AgentWorkspace.bootstrap(workspaceURL: url)
             self.workspacePath = AgentWorkspace.displayPath(for: url)
             self.workspaceStatus = "Workspace ready at \(self.workspacePath)"
+            self.refreshBootstrapStatus()
         } catch {
             self.workspaceStatus = "Failed to create workspace: \(error.localizedDescription)"
         }
     }
 
-    private func applyIdentity() async {
-        guard !self.identityApplying else { return }
-        self.identityApplying = true
-        defer { self.identityApplying = false }
-
-        if self.identityName.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            self.identityStatus = "Please enter a name first."
-            return
-        }
-
-        var identity = AgentIdentity(
-            name: self.identityName,
-            theme: self.identityTheme,
-            emoji: self.identityEmoji)
-
-        if identity.emoji.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty {
-            identity.emoji = AgentIdentityEmoji.suggest(theme: identity.theme)
-            self.identityEmoji = identity.emoji
-        }
-
-        do {
-            let workspaceURL = AgentWorkspace.resolveWorkspaceURL(from: self.workspacePath)
-            try AgentWorkspace.upsertIdentity(workspaceURL: workspaceURL, identity: identity)
-            ClawdisConfigFile.setInboundWorkspace(AgentWorkspace.displayPath(for: workspaceURL))
-            ClawdisConfigFile.setIdentity(identity)
-            self.identityStatus = "Saved identity to AGENTS.md and ~/.clawdis/clawdis.json"
-        } catch {
-            self.identityStatus = "Failed to save identity: \(error.localizedDescription)"
-        }
-    }
-
     private func maybeKickoffOnboardingChat(for pageIndex: Int) {
         guard pageIndex == self.onboardingChatPageIndex else { return }
-        guard !self.hasIdentity else { return }
+        guard self.needsBootstrap else { return }
         guard !self.didAutoKickoff else { return }
         self.didAutoKickoff = true
 

apps/macos/Sources/Clawdis/PermissionsSettings.swift

@@ -58,13 +58,21 @@ struct PermissionStatusList: View {
 struct PermissionRow: View {
     let capability: Capability
     let status: Bool
+    let compact: Bool
     let action: () -> Void
 
+    init(capability: Capability, status: Bool, compact: Bool = false, action: @escaping () -> Void) {
+        self.capability = capability
+        self.status = status
+        self.compact = compact
+        self.action = action
+    }
+
     var body: some View {
-        HStack(spacing: 12) {
+        HStack(spacing: self.compact ? 10 : 12) {
             ZStack {
                 Circle().fill(self.status ? Color.green.opacity(0.2) : Color.gray.opacity(0.15))
-                    .frame(width: 32, height: 32)
+                    .frame(width: self.iconSize, height: self.iconSize)
                 Image(systemName: self.icon)
                     .foregroundStyle(self.status ? Color.green : Color.secondary)
             }
@@ -81,9 +89,11 @@ struct PermissionRow: View {
                     .buttonStyle(.bordered)
             }
         }
-        .padding(.vertical, 6)
+        .padding(.vertical, self.compact ? 4 : 6)
     }
 
+    private var iconSize: CGFloat { self.compact ? 28 : 32 }
+
     private var title: String {
         switch self.capability {
         case .appleScript: "Automation (AppleScript)"

apps/macos/Sources/Clawdis/SettingsRootView.swift

@@ -21,6 +21,10 @@ struct SettingsRootView: View {
                 .tabItem { Label("General", systemImage: "gearshape") }
                 .tag(SettingsTab.general)
 
+            ConnectionsSettings()
+                .tabItem { Label("Connections", systemImage: "link") }
+                .tag(SettingsTab.connections)
+
             VoiceWakeSettings(state: self.state)
                 .tabItem { Label("Voice Wake", systemImage: "waveform.circle") }
                 .tag(SettingsTab.voiceWake)
@@ -125,12 +129,13 @@ struct SettingsRootView: View {
 }
 
 enum SettingsTab: CaseIterable {
-    case general, skills, sessions, cron, config, instances, voiceWake, permissions, debug, about
-    static let windowWidth: CGFloat = 724 // +10% (tabs fit better)
+    case general, connections, skills, sessions, cron, config, instances, voiceWake, permissions, debug, about
+    static let windowWidth: CGFloat = 824 // wider
     static let windowHeight: CGFloat = 790 // +10% (more room)
     var title: String {
         switch self {
         case .general: "General"
+        case .connections: "Connections"
         case .skills: "Skills"
         case .sessions: "Sessions"
         case .cron: "Cron"

apps/macos/Sources/Clawdis/ShellExecutor.swift

@@ -56,8 +56,8 @@ enum ShellExecutor {
             let err = stderrPipe.fileHandleForReading.readToEndSafely()
             let status = Int(process.terminationStatus)
             return ShellResult(
-                stdout: String(decoding: out, as: UTF8.self),
-                stderr: String(decoding: err, as: UTF8.self),
+                stdout: String(bytes: out, encoding: .utf8) ?? "",
+                stderr: String(bytes: err, encoding: .utf8) ?? "",
                 exitCode: status,
                 timedOut: false,
                 success: status == 0,

apps/macos/Sources/Clawdis/SkillsSettings.swift

@@ -6,7 +6,6 @@ struct SkillsSettings: View {
     @Bindable var state: AppState
     @State private var model = SkillsSettingsModel()
     @State private var envEditor: EnvEditorState?
-    @State private var searchQuery = ""
     @State private var filter: SkillsFilter = .all
 
     init(state: AppState = AppStateStore.shared) {
@@ -83,8 +82,7 @@ struct SkillsSettings: View {
                     SkillRow(
                         skill: skill,
                         isBusy: self.model.isBusy(skill: skill),
-                        canInstallLocally: self.state.connectionMode == .local,
-                        defaultInstallTarget: self.defaultInstallTarget(for: skill),
+                        connectionMode: self.state.connectionMode,
                         onToggleEnabled: { enabled in
                             Task { await self.model.setEnabled(skillKey: skill.skillKey, enabled: enabled) }
                         },
@@ -106,7 +104,6 @@ struct SkillsSettings: View {
                 }
             }
             .listStyle(.inset)
-            .searchable(text: self.$searchQuery, placement: .automatic, prompt: "Search skills")
         }
     }
 
@@ -123,31 +120,19 @@ struct SkillsSettings: View {
     }
 
     private var filteredSkills: [SkillStatus] {
-        let trimmed = self.searchQuery.trimmingCharacters(in: .whitespacesAndNewlines)
-        let query = trimmed.lowercased()
-        return self.model.skills.filter { skill in
-            if !query.isEmpty {
-                let matchesName = skill.name.lowercased().contains(query)
-                let matchesDescription = skill.description.lowercased().contains(query)
-                if !(matchesName || matchesDescription) { return false }
-            }
+        self.model.skills.filter { skill in
             switch self.filter {
             case .all:
-                return true
+                true
             case .ready:
-                return !skill.disabled && skill.eligible
+                !skill.disabled && skill.eligible
             case .needsSetup:
-                return !skill.disabled && !skill.eligible
+                !skill.disabled && !skill.eligible
             case .disabled:
-                return skill.disabled
+                skill.disabled
             }
         }
     }
-
-    private func defaultInstallTarget(for skill: SkillStatus) -> InstallTarget {
-        let localPreferred = ["imsg", "peekaboo", "spotify-player"]
-        return localPreferred.contains(skill.skillKey) ? .local : .gateway
-    }
 }
 
 private enum SkillsFilter: String, CaseIterable, Identifiable {
@@ -180,11 +165,10 @@ private enum InstallTarget: String, CaseIterable {
 private struct SkillRow: View {
     let skill: SkillStatus
     let isBusy: Bool
-    let canInstallLocally: Bool
+    let connectionMode: AppState.ConnectionMode
     let onToggleEnabled: (Bool) -> Void
     let onInstall: (SkillInstallOption, InstallTarget) -> Void
     let onSetEnv: (String, Bool) -> Void
-    @State private var installTarget: InstallTarget
 
     private var missingBins: [String] { self.skill.missing.bins }
     private var missingEnv: [String] { self.skill.missing.env }
@@ -193,22 +177,17 @@ private struct SkillRow: View {
     init(
         skill: SkillStatus,
         isBusy: Bool,
-        canInstallLocally: Bool,
-        defaultInstallTarget: InstallTarget,
+        connectionMode: AppState.ConnectionMode,
         onToggleEnabled: @escaping (Bool) -> Void,
         onInstall: @escaping (SkillInstallOption, InstallTarget) -> Void,
         onSetEnv: @escaping (String, Bool) -> Void)
     {
         self.skill = skill
         self.isBusy = isBusy
-        self.canInstallLocally = canInstallLocally
+        self.connectionMode = connectionMode
         self.onToggleEnabled = onToggleEnabled
         self.onInstall = onInstall
         self.onSetEnv = onSetEnv
-        let initialTarget: InstallTarget = (defaultInstallTarget == .local && !canInstallLocally)
-            ? .gateway
-            : defaultInstallTarget
-        self._installTarget = State(initialValue: initialTarget)
     }
 
     var body: some View {
@@ -348,28 +327,31 @@ private struct SkillRow: View {
     private var trailingActions: some View {
         VStack(alignment: .trailing, spacing: 8) {
             if !self.installOptions.isEmpty {
-                HStack(spacing: 6) {
-                    Text("Install on")
-                        .font(.caption)
-                        .foregroundStyle(.secondary)
-                    Picker("Install on", selection: self.$installTarget) {
-                        Text("Gateway")
-                            .tag(InstallTarget.gateway)
-                        Text("This Mac")
-                            .tag(InstallTarget.local)
-                            .disabled(!self.canInstallLocally)
+                ForEach(self.installOptions, id: \.id) { (option: SkillInstallOption) in
+                    HStack(spacing: 6) {
+                        if self.showGatewayInstall {
+                            Button("Install on Gateway") { self.onInstall(option, .gateway) }
+                                .buttonStyle(.borderedProminent)
+                                .disabled(self.isBusy)
+                        }
+                        if self.showGatewayInstall {
+                            Button("Install on This Mac") { self.onInstall(option, .local) }
+                                .buttonStyle(.bordered)
+                                .disabled(self.isBusy)
+                                .help(
+                                    self.localInstallNeedsSwitch
+                                        ? "Switches to Local mode to install on this Mac."
+                                        : "")
+                        } else {
+                            Button("Install on This Mac") { self.onInstall(option, .local) }
+                                .buttonStyle(.borderedProminent)
+                                .disabled(self.isBusy)
+                                .help(
+                                    self.localInstallNeedsSwitch
+                                        ? "Switches to Local mode to install on this Mac."
+                                        : "")
+                        }
                     }
-                    .labelsHidden()
-                    .pickerStyle(.segmented)
-                    .frame(width: 160)
-                    .controlSize(.small)
-                    .help(self.canInstallLocally ? "" : "Local install requires a local gateway connection.")
-                }
-                ForEach(self.installOptions) { option in
-                    Button("Install") { self.onInstall(option, self.installTarget) }
-                        .buttonStyle(.borderedProminent)
-                        .disabled(self.isBusy || self.installBlocked)
-                        .help(self.installBlocked ? "Local install requires a local gateway connection." : "")
                 }
             } else {
                 Toggle("", isOn: self.enabledBinding)
@@ -408,8 +390,12 @@ private struct SkillRow: View {
             !self.missingConfig.isEmpty
     }
 
-    private var installBlocked: Bool {
-        self.installTarget == .local && !self.canInstallLocally
+    private var showGatewayInstall: Bool {
+        self.connectionMode == .remote
+    }
+
+    private var localInstallNeedsSwitch: Bool {
+        self.connectionMode != .local
     }
 
     private func formatConfigValue(_ value: AnyCodable?) -> String {
@@ -521,8 +507,8 @@ final class SkillsSettingsModel {
         await self.withBusy(skill.skillKey) {
             do {
                 if target == .local, AppStateStore.shared.connectionMode != .local {
-                    self.statusMessage = "Local install requires a local gateway connection"
-                    return
+                    AppStateStore.shared.connectionMode = .local
+                    self.statusMessage = "Switched to Local mode to install on this Mac"
                 }
                 let result = try await GatewayConnection.shared.skillsInstall(
                     name: skill.name,

apps/macos/Sources/Clawdis/TailscaleIntegrationSection.swift

@@ -0,0 +1,370 @@
+import SwiftUI
+
+private enum GatewayTailscaleMode: String, CaseIterable, Identifiable {
+    case off
+    case serve
+    case funnel
+
+    var id: String { self.rawValue }
+
+    var label: String {
+        switch self {
+        case .off: "Off"
+        case .serve: "Tailnet (Serve)"
+        case .funnel: "Public (Funnel)"
+        }
+    }
+
+    var description: String {
+        switch self {
+        case .off:
+            "No automatic Tailscale configuration."
+        case .serve:
+            "Tailnet-only HTTPS via Tailscale Serve."
+        case .funnel:
+            "Public HTTPS via Tailscale Funnel (requires auth)."
+        }
+    }
+}
+
+private enum GatewayAuthMode: String, CaseIterable, Identifiable {
+    case system
+    case password
+
+    var id: String { self.rawValue }
+
+    var label: String {
+        switch self {
+        case .system: "System password"
+        case .password: "Shared password"
+        }
+    }
+}
+
+struct TailscaleIntegrationSection: View {
+    let connectionMode: AppState.ConnectionMode
+    let isPaused: Bool
+
+    @Environment(TailscaleService.self) private var tailscaleService
+
+    @State private var hasLoaded = false
+    @State private var tailscaleMode: GatewayTailscaleMode = .off
+    @State private var requireCredentialsForServe = false
+    @State private var authMode: GatewayAuthMode = .system
+    @State private var username: String = ""
+    @State private var password: String = ""
+    @State private var statusMessage: String?
+    @State private var validationMessage: String?
+    @State private var statusTimer: Timer?
+
+    var body: some View {
+        VStack(alignment: .leading, spacing: 10) {
+            Text("Tailscale (dashboard access)")
+                .font(.callout.weight(.semibold))
+
+            self.statusRow
+
+            if !self.tailscaleService.isInstalled {
+                self.installButtons
+            } else {
+                self.modePicker
+                if self.tailscaleMode != .off {
+                    self.accessURLRow
+                }
+                if self.tailscaleMode == .serve {
+                    self.serveAuthSection
+                }
+                if self.tailscaleMode == .funnel {
+                    self.funnelAuthSection
+                }
+            }
+
+            if self.connectionMode != .local {
+                Text("Local mode required. Update settings on the gateway host.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+
+            if let validationMessage {
+                Text(validationMessage)
+                    .font(.caption)
+                    .foregroundStyle(.orange)
+            } else if let statusMessage {
+                Text(statusMessage)
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+        }
+        .padding(12)
+        .background(Color.gray.opacity(0.08))
+        .cornerRadius(10)
+        .disabled(self.connectionMode != .local)
+        .task {
+            guard !self.hasLoaded else { return }
+            self.hasLoaded = true
+            self.loadConfig()
+            await self.tailscaleService.checkTailscaleStatus()
+            self.startStatusTimer()
+        }
+        .onDisappear {
+            self.stopStatusTimer()
+        }
+        .onChange(of: self.tailscaleMode) { _, _ in
+            self.applySettings()
+        }
+        .onChange(of: self.requireCredentialsForServe) { _, _ in
+            self.applySettings()
+        }
+        .onChange(of: self.authMode) { _, _ in
+            self.applySettings()
+        }
+    }
+
+    private var statusRow: some View {
+        HStack(spacing: 8) {
+            Circle()
+                .fill(self.statusColor)
+                .frame(width: 10, height: 10)
+            Text(self.statusText)
+                .font(.callout)
+            Spacer()
+            Button("Refresh") {
+                Task { await self.tailscaleService.checkTailscaleStatus() }
+            }
+            .buttonStyle(.bordered)
+            .controlSize(.small)
+        }
+    }
+
+    private var statusColor: Color {
+        if !self.tailscaleService.isInstalled { return .yellow }
+        if self.tailscaleService.isRunning { return .green }
+        return .orange
+    }
+
+    private var statusText: String {
+        if !self.tailscaleService.isInstalled { return "Tailscale is not installed" }
+        if self.tailscaleService.isRunning { return "Tailscale is installed and running" }
+        return "Tailscale is installed but not running"
+    }
+
+    private var installButtons: some View {
+        HStack(spacing: 12) {
+            Button("App Store") { self.tailscaleService.openAppStore() }
+                .buttonStyle(.link)
+            Button("Direct Download") { self.tailscaleService.openDownloadPage() }
+                .buttonStyle(.link)
+            Button("Setup Guide") { self.tailscaleService.openSetupGuide() }
+                .buttonStyle(.link)
+        }
+        .controlSize(.small)
+    }
+
+    private var modePicker: some View {
+        VStack(alignment: .leading, spacing: 6) {
+            Text("Exposure mode")
+                .font(.callout.weight(.semibold))
+            Picker("Exposure", selection: self.$tailscaleMode) {
+                ForEach(GatewayTailscaleMode.allCases) { mode in
+                    Text(mode.label).tag(mode)
+                }
+            }
+            .pickerStyle(.segmented)
+            Text(self.tailscaleMode.description)
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+    }
+
+    @ViewBuilder
+    private var accessURLRow: some View {
+        if let host = self.tailscaleService.tailscaleHostname {
+            let url = "https://\(host)/ui/"
+            HStack(spacing: 8) {
+                Text("Dashboard URL:")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+                if let link = URL(string: url) {
+                    Link(url, destination: link)
+                        .font(.system(.caption, design: .monospaced))
+                } else {
+                    Text(url)
+                        .font(.system(.caption, design: .monospaced))
+                }
+            }
+        } else if !self.tailscaleService.isRunning {
+            Text("Start Tailscale to get your tailnet hostname.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+        }
+
+        if self.tailscaleService.isInstalled, !self.tailscaleService.isRunning {
+            Button("Start Tailscale") { self.tailscaleService.openTailscaleApp() }
+                .buttonStyle(.borderedProminent)
+                .controlSize(.small)
+        }
+    }
+
+    private var serveAuthSection: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Toggle("Require credentials", isOn: self.$requireCredentialsForServe)
+                .toggleStyle(.checkbox)
+            if self.requireCredentialsForServe {
+                self.authModePicker
+                self.authFields
+            } else {
+                Text("Serve uses Tailscale identity headers; no password required.")
+                    .font(.caption)
+                    .foregroundStyle(.secondary)
+            }
+        }
+    }
+
+    private var funnelAuthSection: some View {
+        VStack(alignment: .leading, spacing: 8) {
+            Text("Funnel requires authentication.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            self.authModePicker
+            self.authFields
+        }
+    }
+
+    private var authModePicker: some View {
+        Picker("Auth", selection: self.$authMode) {
+            ForEach(GatewayAuthMode.allCases) { mode in
+                Text(mode.label).tag(mode)
+            }
+        }
+        .pickerStyle(.segmented)
+    }
+
+    @ViewBuilder
+    private var authFields: some View {
+        if self.authMode == .system {
+            TextField("Username (optional)", text: self.$username)
+                .textFieldStyle(.roundedBorder)
+                .frame(maxWidth: 240)
+                .onSubmit { self.applySettings() }
+        } else {
+            SecureField("Password", text: self.$password)
+                .textFieldStyle(.roundedBorder)
+                .frame(maxWidth: 240)
+                .onSubmit { self.applySettings() }
+            Text("Stored in ~/.clawdis/clawdis.json. Prefer CLAWDIS_GATEWAY_PASSWORD for production.")
+                .font(.caption)
+                .foregroundStyle(.secondary)
+            Button("Update password") { self.applySettings() }
+                .buttonStyle(.bordered)
+                .controlSize(.small)
+        }
+    }
+
+    private func loadConfig() {
+        let gateway = ClawdisConfigFile.loadGatewayDict()
+        let tailscale = gateway["tailscale"] as? [String: Any] ?? [:]
+        let modeRaw = (tailscale["mode"] as? String) ?? "off"
+        self.tailscaleMode = GatewayTailscaleMode(rawValue: modeRaw) ?? .off
+
+        let auth = gateway["auth"] as? [String: Any] ?? [:]
+        let authModeRaw = auth["mode"] as? String
+        let allowTailscale = auth["allowTailscale"] as? Bool
+
+        if let authModeRaw, authModeRaw == "password" { self.authMode = .password }
+        else { self.authMode = .system }
+
+        self.username = auth["username"] as? String ?? ""
+        self.password = auth["password"] as? String ?? ""
+
+        if self.tailscaleMode == .serve {
+            let usesExplicitAuth = authModeRaw == "password" || authModeRaw == "system"
+            if let allowTailscale, allowTailscale == false {
+                self.requireCredentialsForServe = true
+            } else {
+                self.requireCredentialsForServe = usesExplicitAuth
+            }
+        } else {
+            self.requireCredentialsForServe = false
+        }
+    }
+
+    private func applySettings() {
+        guard self.hasLoaded else { return }
+        self.validationMessage = nil
+        self.statusMessage = nil
+
+        let trimmedPassword = self.password.trimmingCharacters(in: .whitespacesAndNewlines)
+        if (self.tailscaleMode == .funnel || (self.tailscaleMode == .serve && self.requireCredentialsForServe)),
+           self.authMode == .password,
+           trimmedPassword.isEmpty
+        {
+            self.validationMessage = "Password required for this mode."
+            return
+        }
+
+        ClawdisConfigFile.updateGatewayDict { gateway in
+            var tailscale = gateway["tailscale"] as? [String: Any] ?? [:]
+            tailscale["mode"] = self.tailscaleMode.rawValue
+            gateway["tailscale"] = tailscale
+
+            if self.tailscaleMode != .off {
+                gateway["bind"] = "loopback"
+            }
+
+            guard self.tailscaleMode != .off else { return }
+            var auth = gateway["auth"] as? [String: Any] ?? [:]
+
+            if self.tailscaleMode == .serve && !self.requireCredentialsForServe {
+                auth["allowTailscale"] = true
+                auth.removeValue(forKey: "mode")
+                auth.removeValue(forKey: "password")
+                auth.removeValue(forKey: "username")
+            } else {
+                auth["allowTailscale"] = false
+                auth["mode"] = self.authMode.rawValue
+                if self.authMode == .password {
+                    auth["password"] = trimmedPassword
+                    auth.removeValue(forKey: "username")
+                } else {
+                    let trimmedUsername = self.username.trimmingCharacters(in: .whitespacesAndNewlines)
+                    if trimmedUsername.isEmpty {
+                        auth.removeValue(forKey: "username")
+                    } else {
+                        auth["username"] = trimmedUsername
+                    }
+                    auth.removeValue(forKey: "password")
+                }
+            }
+
+            if auth.isEmpty {
+                gateway.removeValue(forKey: "auth")
+            } else {
+                gateway["auth"] = auth
+            }
+        }
+
+        if self.connectionMode == .local, !self.isPaused {
+            self.statusMessage = "Saved to ~/.clawdis/clawdis.json. Restarting gateway…"
+        } else {
+            self.statusMessage = "Saved to ~/.clawdis/clawdis.json. Restart the gateway to apply."
+        }
+        self.restartGatewayIfNeeded()
+    }
+
+    private func restartGatewayIfNeeded() {
+        guard self.connectionMode == .local, !self.isPaused else { return }
+        Task { await GatewayLaunchAgentManager.kickstart() }
+    }
+
+    private func startStatusTimer() {
+        self.stopStatusTimer()
+        self.statusTimer = Timer.scheduledTimer(withTimeInterval: 5, repeats: true) { _ in
+            Task { await self.tailscaleService.checkTailscaleStatus() }
+        }
+    }
+
+    private func stopStatusTimer() {
+        self.statusTimer?.invalidate()
+        self.statusTimer = nil
+    }
+}

apps/macos/Sources/Clawdis/TailscaleService.swift

@@ -0,0 +1,150 @@
+import AppKit
+import Foundation
+import Observation
+import os
+
+/// Manages Tailscale integration and status checking.
+@Observable
+@MainActor
+final class TailscaleService {
+    static let shared = TailscaleService()
+
+    /// Tailscale local API endpoint.
+    private static let tailscaleAPIEndpoint = "http://100.100.100.100/api/data"
+
+    /// API request timeout in seconds.
+    private static let apiTimeoutInterval: TimeInterval = 5.0
+
+    private let logger = Logger(subsystem: "com.steipete.clawdis", category: "tailscale")
+
+    /// Indicates if the Tailscale app is installed on the system.
+    private(set) var isInstalled = false
+
+    /// Indicates if Tailscale is currently running.
+    private(set) var isRunning = false
+
+    /// The Tailscale hostname for this device (e.g., "my-mac.tailnet.ts.net").
+    private(set) var tailscaleHostname: String?
+
+    /// The Tailscale IPv4 address for this device.
+    private(set) var tailscaleIP: String?
+
+    /// Error message if status check fails.
+    private(set) var statusError: String?
+
+    private init() {
+        Task { await self.checkTailscaleStatus() }
+    }
+
+    func checkAppInstallation() -> Bool {
+        let installed = FileManager.default.fileExists(atPath: "/Applications/Tailscale.app")
+        self.logger.info("Tailscale app installed: \(installed)")
+        return installed
+    }
+
+    private struct TailscaleAPIResponse: Codable {
+        let status: String
+        let deviceName: String
+        let tailnetName: String
+        let iPv4: String?
+
+        private enum CodingKeys: String, CodingKey {
+            case status = "Status"
+            case deviceName = "DeviceName"
+            case tailnetName = "TailnetName"
+            case iPv4 = "IPv4"
+        }
+    }
+
+    private func fetchTailscaleStatus() async -> TailscaleAPIResponse? {
+        guard let url = URL(string: Self.tailscaleAPIEndpoint) else {
+            self.logger.error("Invalid Tailscale API URL")
+            return nil
+        }
+
+        do {
+            let configuration = URLSessionConfiguration.default
+            configuration.timeoutIntervalForRequest = Self.apiTimeoutInterval
+            let session = URLSession(configuration: configuration)
+
+            let (data, response) = try await session.data(from: url)
+            guard let httpResponse = response as? HTTPURLResponse,
+                  httpResponse.statusCode == 200
+            else {
+                self.logger.warning("Tailscale API returned non-200 status")
+                return nil
+            }
+
+            let decoder = JSONDecoder()
+            return try decoder.decode(TailscaleAPIResponse.self, from: data)
+        } catch {
+            self.logger.debug("Failed to fetch Tailscale status: \(String(describing: error))")
+            return nil
+        }
+    }
+
+    func checkTailscaleStatus() async {
+        self.isInstalled = self.checkAppInstallation()
+        guard self.isInstalled else {
+            self.isRunning = false
+            self.tailscaleHostname = nil
+            self.tailscaleIP = nil
+            self.statusError = "Tailscale is not installed"
+            return
+        }
+
+        if let apiResponse = await fetchTailscaleStatus() {
+            self.isRunning = apiResponse.status.lowercased() == "running"
+
+            if self.isRunning {
+                let deviceName = apiResponse.deviceName
+                    .lowercased()
+                    .replacingOccurrences(of: " ", with: "-")
+                let tailnetName = apiResponse.tailnetName
+                    .replacingOccurrences(of: ".ts.net", with: "")
+                    .replacingOccurrences(of: ".tailscale.net", with: "")
+
+                self.tailscaleHostname = "\(deviceName).\(tailnetName).ts.net"
+                self.tailscaleIP = apiResponse.iPv4
+                self.statusError = nil
+
+                self.logger.info(
+                    "Tailscale running host=\(self.tailscaleHostname ?? "nil") ip=\(self.tailscaleIP ?? "nil")")
+            } else {
+                self.tailscaleHostname = nil
+                self.tailscaleIP = nil
+                self.statusError = "Tailscale is not running"
+            }
+        } else {
+            self.isRunning = false
+            self.tailscaleHostname = nil
+            self.tailscaleIP = nil
+            self.statusError = "Please start the Tailscale app"
+            self.logger.info("Tailscale API not responding; app likely not running")
+        }
+    }
+
+    func openTailscaleApp() {
+        if let url = URL(string: "file:///Applications/Tailscale.app") {
+            NSWorkspace.shared.open(url)
+        }
+    }
+
+    func openAppStore() {
+        if let url = URL(string: "https://apps.apple.com/us/app/tailscale/id1475387142") {
+            NSWorkspace.shared.open(url)
+        }
+    }
+
+    func openDownloadPage() {
+        if let url = URL(string: "https://tailscale.com/download/macos") {
+            NSWorkspace.shared.open(url)
+        }
+    }
+
+    func openSetupGuide() {
+        if let url = URL(string: "https://tailscale.com/kb/1017/install/") {
+            NSWorkspace.shared.open(url)
+        }
+    }
+}

apps/macos/Tests/ClawdisIPCTests/AgentIdentityTests.swift

@@ -1,21 +0,0 @@
-import Foundation
-import Testing
-@testable import Clawdis
-
-@Suite
-struct AgentIdentityTests {
-    @Test
-    func isEmptyTreatsWhitespaceAsEmpty() {
-        #expect(AgentIdentity(name: " ", theme: "\n", emoji: "\t").isEmpty == true)
-        #expect(AgentIdentity(name: "Pi", theme: "", emoji: "").isEmpty == false)
-    }
-
-    @Test
-    func emojiSuggestMatchesKnownThemes() {
-        #expect(AgentIdentityEmoji.suggest(theme: "") == "🦞")
-        #expect(AgentIdentityEmoji.suggest(theme: "shark") == "🦈")
-        #expect(AgentIdentityEmoji.suggest(theme: "  Octopus helper  ") == "🐙")
-        #expect(AgentIdentityEmoji.suggest(theme: "unknown") == "🦞")
-    }
-}
-

apps/macos/Tests/ClawdisIPCTests/AgentWorkspaceTests.swift

@@ -48,4 +48,76 @@ struct AgentWorkspaceTests {
         let second = try AgentWorkspace.bootstrap(workspaceURL: tmp)
         #expect(second == agentsURL)
     }
+
+    @Test
+    func bootstrapSafetyRejectsNonEmptyFolderWithoutAgents() throws {
+        let tmp = FileManager.default.temporaryDirectory
+            .appendingPathComponent("clawdis-ws-\(UUID().uuidString)", isDirectory: true)
+        defer { try? FileManager.default.removeItem(at: tmp) }
+        try FileManager.default.createDirectory(at: tmp, withIntermediateDirectories: true)
+        let marker = tmp.appendingPathComponent("notes.txt")
+        try "hello".write(to: marker, atomically: true, encoding: .utf8)
+
+        let result = AgentWorkspace.bootstrapSafety(for: tmp)
+        switch result {
+        case .unsafe:
+            break
+        case .safe:
+            #expect(false, "Expected unsafe bootstrap safety result.")
+        }
+    }
+
+    @Test
+    func bootstrapSafetyAllowsExistingAgentsFile() throws {
+        let tmp = FileManager.default.temporaryDirectory
+            .appendingPathComponent("clawdis-ws-\(UUID().uuidString)", isDirectory: true)
+        defer { try? FileManager.default.removeItem(at: tmp) }
+        try FileManager.default.createDirectory(at: tmp, withIntermediateDirectories: true)
+        let agents = tmp.appendingPathComponent(AgentWorkspace.agentsFilename)
+        try "# AGENTS.md".write(to: agents, atomically: true, encoding: .utf8)
+
+        let result = AgentWorkspace.bootstrapSafety(for: tmp)
+        switch result {
+        case .safe:
+            break
+        case .unsafe:
+            #expect(false, "Expected safe bootstrap safety result.")
+        }
+    }
+
+    @Test
+    func bootstrapSkipsBootstrapFileWhenWorkspaceHasContent() throws {
+        let tmp = FileManager.default.temporaryDirectory
+            .appendingPathComponent("clawdis-ws-\(UUID().uuidString)", isDirectory: true)
+        defer { try? FileManager.default.removeItem(at: tmp) }
+        try FileManager.default.createDirectory(at: tmp, withIntermediateDirectories: true)
+        let marker = tmp.appendingPathComponent("notes.txt")
+        try "hello".write(to: marker, atomically: true, encoding: .utf8)
+
+        _ = try AgentWorkspace.bootstrap(workspaceURL: tmp)
+
+        let bootstrapURL = tmp.appendingPathComponent(AgentWorkspace.bootstrapFilename)
+        #expect(!FileManager.default.fileExists(atPath: bootstrapURL.path))
+    }
+
+    @Test
+    func needsBootstrapFalseWhenIdentityAlreadySet() throws {
+        let tmp = FileManager.default.temporaryDirectory
+            .appendingPathComponent("clawdis-ws-\(UUID().uuidString)", isDirectory: true)
+        defer { try? FileManager.default.removeItem(at: tmp) }
+        try FileManager.default.createDirectory(at: tmp, withIntermediateDirectories: true)
+        let identityURL = tmp.appendingPathComponent(AgentWorkspace.identityFilename)
+        try """
+        # IDENTITY.md - Agent Identity
+
+        - Name: Clawd
+        - Creature: Space Lobster
+        - Vibe: Helpful
+        - Emoji: lobster
+        """.write(to: identityURL, atomically: true, encoding: .utf8)
+        let bootstrapURL = tmp.appendingPathComponent(AgentWorkspace.bootstrapFilename)
+        try "bootstrap".write(to: bootstrapURL, atomically: true, encoding: .utf8)
+
+        #expect(!AgentWorkspace.needsBootstrap(workspaceURL: tmp))
+    }
 }

apps/shared/ClawdisKit/Sources/ClawdisChatUI/ChatComposer.swift

@@ -41,7 +41,7 @@ struct ClawdisChatComposer: View {
                     .lineLimit(2)
             }
         }
-        .padding(8)
+        .padding(self.composerPadding)
         .background(
             RoundedRectangle(cornerRadius: 18, style: .continuous)
                 .fill(ClawdisChatTheme.composerBackground)
@@ -144,9 +144,12 @@ struct ClawdisChatComposer: View {
                         self.sendButton
                     }
                 }
-                .padding(8)
             }
-            .frame(minHeight: 44, idealHeight: 44, maxHeight: 96)
+            .padding(self.editorPadding)
+            .frame(
+                minHeight: self.editorMinHeight,
+                idealHeight: self.editorMinHeight,
+                maxHeight: self.editorMaxHeight)
     }
 
     private var connectionPill: some View {
@@ -179,7 +182,7 @@ struct ClawdisChatComposer: View {
             ChatComposerTextView(text: self.$viewModel.input) {
                 self.viewModel.send()
             }
-            .frame(minHeight: 32, idealHeight: 32, maxHeight: 72)
+            .frame(minHeight: self.textMinHeight, idealHeight: self.textMinHeight, maxHeight: self.textMaxHeight)
             .padding(.horizontal, 6)
             .padding(.vertical, 4)
             #else
@@ -254,6 +257,30 @@ struct ClawdisChatComposer: View {
         self.style == .standard
     }
 
+    private var composerPadding: CGFloat {
+        self.style == .onboarding ? 6 : 8
+    }
+
+    private var editorPadding: CGFloat {
+        self.style == .onboarding ? 6 : 8
+    }
+
+    private var editorMinHeight: CGFloat {
+        self.style == .onboarding ? 38 : 44
+    }
+
+    private var editorMaxHeight: CGFloat {
+        self.style == .onboarding ? 72 : 96
+    }
+
+    private var textMinHeight: CGFloat {
+        self.style == .onboarding ? 28 : 32
+    }
+
+    private var textMaxHeight: CGFloat {
+        self.style == .onboarding ? 60 : 72
+    }
+
     #if os(macOS)
     private func pickFilesMac() {
         let panel = NSOpenPanel()

apps/shared/ClawdisKit/Sources/ClawdisChatUI/ChatMessageViews.swift

@@ -6,12 +6,139 @@ private enum ChatUIConstants {
     static let bubbleCorner: CGFloat = 18
 }
 
+private struct ChatBubbleShape: InsettableShape {
+    enum Tail {
+        case left
+        case right
+        case none
+    }
+
+    let cornerRadius: CGFloat
+    let tail: Tail
+    var insetAmount: CGFloat = 0
+
+    private let tailWidth: CGFloat = 7
+    private let tailBaseHeight: CGFloat = 9
+
+    func inset(by amount: CGFloat) -> ChatBubbleShape {
+        var copy = self
+        copy.insetAmount += amount
+        return copy
+    }
+
+    func path(in rect: CGRect) -> Path {
+        let rect = rect.insetBy(dx: self.insetAmount, dy: self.insetAmount)
+        switch self.tail {
+        case .left:
+            return self.leftTailPath(in: rect, radius: self.cornerRadius)
+        case .right:
+            return self.rightTailPath(in: rect, radius: self.cornerRadius)
+        case .none:
+            return Path(roundedRect: rect, cornerRadius: self.cornerRadius)
+        }
+    }
+
+    private func rightTailPath(in rect: CGRect, radius r: CGFloat) -> Path {
+        var path = Path()
+        let bubbleMinX = rect.minX
+        let bubbleMaxX = rect.maxX - self.tailWidth
+        let bubbleMinY = rect.minY
+        let bubbleMaxY = rect.maxY
+
+        let available = max(4, bubbleMaxY - bubbleMinY - 2 * r)
+        let baseH = min(tailBaseHeight, available)
+        let baseBottomY = bubbleMaxY - max(r * 0.45, 6)
+        let baseTopY = baseBottomY - baseH
+        let midY = (baseTopY + baseBottomY) / 2
+
+        let baseTop = CGPoint(x: bubbleMaxX, y: baseTopY)
+        let baseBottom = CGPoint(x: bubbleMaxX, y: baseBottomY)
+        let tip = CGPoint(x: bubbleMaxX + self.tailWidth, y: midY)
+
+        path.move(to: CGPoint(x: bubbleMinX + r, y: bubbleMinY))
+        path.addLine(to: CGPoint(x: bubbleMaxX - r, y: bubbleMinY))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMaxX, y: bubbleMinY + r),
+            control: CGPoint(x: bubbleMaxX, y: bubbleMinY))
+        path.addLine(to: baseTop)
+        path.addCurve(
+            to: tip,
+            control1: CGPoint(x: bubbleMaxX + self.tailWidth * 0.2, y: baseTopY + baseH * 0.05),
+            control2: CGPoint(x: bubbleMaxX + self.tailWidth * 0.95, y: midY - baseH * 0.15))
+        path.addCurve(
+            to: baseBottom,
+            control1: CGPoint(x: bubbleMaxX + self.tailWidth * 0.95, y: midY + baseH * 0.15),
+            control2: CGPoint(x: bubbleMaxX + self.tailWidth * 0.2, y: baseBottomY - baseH * 0.05))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMaxX - r, y: bubbleMaxY),
+            control: CGPoint(x: bubbleMaxX, y: bubbleMaxY))
+        path.addLine(to: CGPoint(x: bubbleMinX + r, y: bubbleMaxY))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMinX, y: bubbleMaxY - r),
+            control: CGPoint(x: bubbleMinX, y: bubbleMaxY))
+        path.addLine(to: CGPoint(x: bubbleMinX, y: bubbleMinY + r))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMinX + r, y: bubbleMinY),
+            control: CGPoint(x: bubbleMinX, y: bubbleMinY))
+
+        return path
+    }
+
+    private func leftTailPath(in rect: CGRect, radius r: CGFloat) -> Path {
+        var path = Path()
+        let bubbleMinX = rect.minX + self.tailWidth
+        let bubbleMaxX = rect.maxX
+        let bubbleMinY = rect.minY
+        let bubbleMaxY = rect.maxY
+
+        let available = max(4, bubbleMaxY - bubbleMinY - 2 * r)
+        let baseH = min(tailBaseHeight, available)
+        let baseBottomY = bubbleMaxY - max(r * 0.45, 6)
+        let baseTopY = baseBottomY - baseH
+        let midY = (baseTopY + baseBottomY) / 2
+
+        let baseTop = CGPoint(x: bubbleMinX, y: baseTopY)
+        let baseBottom = CGPoint(x: bubbleMinX, y: baseBottomY)
+        let tip = CGPoint(x: bubbleMinX - self.tailWidth, y: midY)
+
+        path.move(to: CGPoint(x: bubbleMinX + r, y: bubbleMinY))
+        path.addLine(to: CGPoint(x: bubbleMaxX - r, y: bubbleMinY))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMaxX, y: bubbleMinY + r),
+            control: CGPoint(x: bubbleMaxX, y: bubbleMinY))
+        path.addLine(to: CGPoint(x: bubbleMaxX, y: bubbleMaxY - r))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMaxX - r, y: bubbleMaxY),
+            control: CGPoint(x: bubbleMaxX, y: bubbleMaxY))
+        path.addLine(to: CGPoint(x: bubbleMinX + r, y: bubbleMaxY))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMinX, y: bubbleMaxY - r),
+            control: CGPoint(x: bubbleMinX, y: bubbleMaxY))
+        path.addLine(to: baseBottom)
+        path.addCurve(
+            to: tip,
+            control1: CGPoint(x: bubbleMinX - self.tailWidth * 0.2, y: baseBottomY - baseH * 0.05),
+            control2: CGPoint(x: bubbleMinX - self.tailWidth * 0.95, y: midY + baseH * 0.15))
+        path.addCurve(
+            to: baseTop,
+            control1: CGPoint(x: bubbleMinX - self.tailWidth * 0.95, y: midY - baseH * 0.15),
+            control2: CGPoint(x: bubbleMinX - self.tailWidth * 0.2, y: baseTopY + baseH * 0.05))
+        path.addLine(to: CGPoint(x: bubbleMinX, y: bubbleMinY + r))
+        path.addQuadCurve(
+            to: CGPoint(x: bubbleMinX + r, y: bubbleMinY),
+            control: CGPoint(x: bubbleMinX, y: bubbleMinY))
+
+        return path
+    }
+}
+
 @MainActor
 struct ChatMessageBubble: View {
     let message: ClawdisChatMessage
+    let style: ClawdisChatView.Style
 
     var body: some View {
-        ChatMessageBody(message: self.message, isUser: self.isUser)
+        ChatMessageBody(message: self.message, isUser: self.isUser, style: self.style)
             .frame(maxWidth: ChatUIConstants.bubbleMaxWidth, alignment: self.isUser ? .trailing : .leading)
             .frame(maxWidth: .infinity, alignment: self.isUser ? .trailing : .leading)
             .padding(.horizontal, 2)
@@ -24,6 +151,7 @@ struct ChatMessageBubble: View {
 private struct ChatMessageBody: View {
     let message: ClawdisChatMessage
     let isUser: Bool
+    let style: ClawdisChatView.Style
 
     var body: some View {
         let text = self.primaryText
@@ -73,8 +201,11 @@ private struct ChatMessageBody: View {
         .padding(.horizontal, 12)
         .foregroundStyle(textColor)
         .background(self.bubbleBackground)
+        .clipShape(self.bubbleShape)
         .overlay(self.bubbleBorder)
-        .clipShape(RoundedRectangle(cornerRadius: ChatUIConstants.bubbleCorner, style: .continuous))
+        .shadow(color: self.bubbleShadowColor, radius: self.bubbleShadowRadius, y: self.bubbleShadowYOffset)
+        .padding(.leading, self.tailPaddingLeading)
+        .padding(.trailing, self.tailPaddingTrailing)
     }
 
     private var primaryText: String {
@@ -86,16 +217,67 @@ private struct ChatMessageBody: View {
         self.message.content.filter { ($0.type ?? "text") != "text" }
     }
 
+    private var bubbleFillColor: Color {
+        if self.isUser {
+            return ClawdisChatTheme.userBubble
+        }
+        if self.style == .onboarding {
+            return ClawdisChatTheme.onboardingAssistantBubble
+        }
+        return ClawdisChatTheme.assistantBubble
+    }
+
     private var bubbleBackground: AnyShapeStyle {
-        let fill = self.isUser ? ClawdisChatTheme.userBubble : ClawdisChatTheme.assistantBubble
-        return AnyShapeStyle(fill)
+        AnyShapeStyle(self.bubbleFillColor)
+    }
+
+    private var bubbleBorderColor: Color {
+        if self.isUser {
+            return Color.white.opacity(0.12)
+        }
+        if self.style == .onboarding {
+            return ClawdisChatTheme.onboardingAssistantBorder
+        }
+        return Color.black.opacity(0.08)
+    }
+
+    private var bubbleBorderWidth: CGFloat {
+        if self.isUser { return 0.5 }
+        if self.style == .onboarding { return 0.8 }
+        return 1
     }
 
     private var bubbleBorder: some View {
-        RoundedRectangle(cornerRadius: ChatUIConstants.bubbleCorner, style: .continuous)
-            .strokeBorder(
-                self.isUser ? Color.white.opacity(0.12) : Color.black.opacity(0.08),
-                lineWidth: self.isUser ? 0.5 : 1)
+        self.bubbleShape.strokeBorder(self.bubbleBorderColor, lineWidth: self.bubbleBorderWidth)
+    }
+
+    private var bubbleShape: ChatBubbleShape {
+        ChatBubbleShape(cornerRadius: ChatUIConstants.bubbleCorner, tail: self.bubbleTail)
+    }
+
+    private var bubbleTail: ChatBubbleShape.Tail {
+        guard self.style == .onboarding else { return .none }
+        return self.isUser ? .right : .left
+    }
+
+    private var tailPaddingLeading: CGFloat {
+        self.style == .onboarding && !self.isUser ? 8 : 0
+    }
+
+    private var tailPaddingTrailing: CGFloat {
+        self.style == .onboarding && self.isUser ? 8 : 0
+    }
+
+    private var bubbleShadowColor: Color {
+        self.style == .onboarding && !self.isUser ? Color.black.opacity(0.28) : .clear
+    }
+
+    private var bubbleShadowRadius: CGFloat {
+        self.style == .onboarding && !self.isUser ? 6 : 0
+    }
+
+    private var bubbleShadowYOffset: CGFloat {
+        self.style == .onboarding && !self.isUser ? 2 : 0
     }
 }
 
@@ -230,12 +412,18 @@ private struct MarkdownTextView: View {
     let textColor: Color
 
     var body: some View {
-        if let attributed = try? AttributedString(markdown: self.text) {
+        let normalized = self.text.replacingOccurrences(
+            of: "(?<!\\n)\\n(?!\\n)",
+            with: " ",
+            options: .regularExpression)
+        let options = AttributedString.MarkdownParsingOptions(
+            interpretedSyntax: .inlineOnlyPreservingWhitespace)
+        if let attributed = try? AttributedString(markdown: normalized, options: options) {
             Text(attributed)
                 .font(.system(size: 14))
                 .foregroundStyle(self.textColor)
         } else {
-            Text(self.text)
+            Text(normalized)
                 .font(.system(size: 14))
                 .foregroundStyle(self.textColor)
         }

apps/shared/ClawdisKit/Sources/ClawdisChatUI/ChatTheme.swift

@@ -47,6 +47,24 @@ enum ClawdisChatTheme {
         #endif
     }
 
+    static var onboardingAssistantBubble: Color {
+        #if os(macOS)
+        let base = NSColor.controlBackgroundColor
+        let blended = base.blended(withFraction: 0.22, of: .white) ?? base
+        return Color(nsColor: blended)
+        #else
+        Color(uiColor: .secondarySystemBackground)
+        #endif
+    }
+
+    static var onboardingAssistantBorder: Color {
+        #if os(macOS)
+        Color.white.opacity(0.12)
+        #else
+        Color.white.opacity(0.12)
+        #endif
+    }
+
     static var userText: Color { .white }
 
     static var assistantText: Color {

apps/shared/ClawdisKit/Sources/ClawdisChatUI/ChatView.swift

@@ -70,7 +70,7 @@ public struct ClawdisChatView: View {
             ScrollView {
                 LazyVStack(spacing: Layout.messageSpacing) {
                     ForEach(self.visibleMessages) { msg in
-                        ChatMessageBubble(message: msg)
+                        ChatMessageBubble(message: msg, style: self.style)
                             .frame(
                                 maxWidth: .infinity,
                                 alignment: msg.role.lowercased() == "user" ? .trailing : .leading)

apps/shared/ClawdisKit/Sources/ClawdisKit/CanvasA2UIAction.swift

@@ -1,6 +1,53 @@
 import Foundation
 
 public enum ClawdisCanvasA2UIAction: Sendable {
+    public struct AgentMessageContext: Sendable {
+        public struct Session: Sendable {
+            public var key: String
+            public var surfaceId: String
+
+            public init(key: String, surfaceId: String) {
+                self.key = key
+                self.surfaceId = surfaceId
+            }
+        }
+
+        public struct Component: Sendable {
+            public var id: String
+            public var host: String
+            public var instanceId: String
+
+            public init(id: String, host: String, instanceId: String) {
+                self.id = id
+                self.host = host
+                self.instanceId = instanceId
+            }
+        }
+
+        public var actionName: String
+        public var session: Session
+        public var component: Component
+        public var contextJSON: String?
+
+        public init(actionName: String, session: Session, component: Component, contextJSON: String?) {
+            self.actionName = actionName
+            self.session = session
+            self.component = component
+            self.contextJSON = contextJSON
+        }
+    }
+
+    public static func extractActionName(_ userAction: [String: Any]) -> String? {
+        let keys = ["name", "action"]
+        for key in keys {
+            if let raw = userAction[key] as? String {
+                let trimmed = raw.trimmingCharacters(in: .whitespacesAndNewlines)
+                if !trimmed.isEmpty { return trimmed }
+            }
+        }
+        return nil
+    }
+
     public static func sanitizeTagValue(_ value: String) -> String {
         let trimmed = value.trimmingCharacters(in: .whitespacesAndNewlines)
         let nonEmpty = trimmed.isEmpty ? "-" : trimmed
@@ -19,25 +66,16 @@ public enum ClawdisCanvasA2UIAction: Sendable {
         return str
     }
 
-    public static func formatAgentMessage(
-        actionName: String,
-        sessionKey: String,
-        surfaceId: String,
-        sourceComponentId: String,
-        host: String,
-        instanceId: String,
-        contextJSON: String?)
-        -> String
-    {
-        let ctxSuffix = contextJSON.flatMap { $0.isEmpty ? nil : " ctx=\($0)" } ?? ""
+    public static func formatAgentMessage(_ context: AgentMessageContext) -> String {
+        let ctxSuffix = context.contextJSON.flatMap { $0.isEmpty ? nil : " ctx=\($0)" } ?? ""
         return [
             "CANVAS_A2UI",
-            "action=\(self.sanitizeTagValue(actionName))",
-            "session=\(self.sanitizeTagValue(sessionKey))",
-            "surface=\(self.sanitizeTagValue(surfaceId))",
-            "component=\(self.sanitizeTagValue(sourceComponentId))",
-            "host=\(self.sanitizeTagValue(host))",
-            "instance=\(self.sanitizeTagValue(instanceId))\(ctxSuffix)",
+            "action=\(self.sanitizeTagValue(context.actionName))",
+            "session=\(self.sanitizeTagValue(context.session.key))",
+            "surface=\(self.sanitizeTagValue(context.session.surfaceId))",
+            "component=\(self.sanitizeTagValue(context.component.id))",
+            "host=\(self.sanitizeTagValue(context.component.host))",
+            "instance=\(self.sanitizeTagValue(context.component.instanceId))\(ctxSuffix)",
             "default=update_canvas",
         ].joined(separator: " ")
     }

apps/shared/ClawdisKit/Sources/ClawdisKit/CanvasA2UIJSONL.swift

@@ -27,7 +27,12 @@ public enum ClawdisCanvasA2UIJSONL: Sendable {
     }
 
     public static func validateV0_8(_ items: [ParsedItem]) throws {
-        let allowed = Set(["beginRendering", "surfaceUpdate", "dataModelUpdate", "deleteSurface"])
+        let allowed = Set([
+            "beginRendering",
+            "surfaceUpdate",
+            "dataModelUpdate",
+            "deleteSurface",
+        ])
         for item in items {
             guard let dict = item.message.value as? [String: AnyCodable] else {
                 throw NSError(domain: "A2UI", code: 1, userInfo: [
@@ -39,7 +44,8 @@ public enum ClawdisCanvasA2UIJSONL: Sendable {
                 throw NSError(domain: "A2UI", code: 2, userInfo: [
                     NSLocalizedDescriptionKey: """
                     A2UI JSONL line \(item.lineNumber): looks like A2UI v0.9 (`createSurface`).
-                    Canvas currently supports A2UI v0.8 server→client messages (`beginRendering`, `surfaceUpdate`, `dataModelUpdate`, `deleteSurface`).
+                    Canvas currently supports A2UI v0.8 server→client messages
+                    (`beginRendering`, `surfaceUpdate`, `dataModelUpdate`, `deleteSurface`).
                     """,
                 ])
             }

apps/shared/ClawdisKit/Tests/ClawdisKitTests/CanvasA2UIActionTests.swift

@@ -9,15 +9,20 @@ import Testing
         #expect(ClawdisCanvasA2UIAction.sanitizeTagValue("macOS 26.2") == "macOS_26.2")
     }
 
+    @Test func extractActionNameAcceptsNameOrAction() {
+        #expect(ClawdisCanvasA2UIAction.extractActionName(["name": "Hello"]) == "Hello")
+        #expect(ClawdisCanvasA2UIAction.extractActionName(["action": "Wave"]) == "Wave")
+        #expect(ClawdisCanvasA2UIAction.extractActionName(["name": "  ", "action": "Fallback"]) == "Fallback")
+        #expect(ClawdisCanvasA2UIAction.extractActionName(["action": " "]) == nil)
+    }
+
     @Test func formatAgentMessageIsTokenEfficientAndUnambiguous() {
-        let msg = ClawdisCanvasA2UIAction.formatAgentMessage(
+        let messageContext = ClawdisCanvasA2UIAction.AgentMessageContext(
             actionName: "Get Weather",
-            sessionKey: "main",
-            surfaceId: "main",
-            sourceComponentId: "btnWeather",
-            host: "Peter’s iPad",
-            instanceId: "ipad16,6",
+            session: .init(key: "main", surfaceId: "main"),
+            component: .init(id: "btnWeather", host: "Peter’s iPad", instanceId: "ipad16,6"),
             contextJSON: "{\"city\":\"Vienna\"}")
+        let msg = ClawdisCanvasA2UIAction.formatAgentMessage(messageContext)
 
         #expect(msg.contains("CANVAS_A2UI "))
         #expect(msg.contains("action=Get_Weather"))

apps/shared/ClawdisKit/Tools/CanvasA2UI/bootstrap.js

@@ -176,7 +176,11 @@ class ClawdisA2UIHost extends LitElement {
       height: 100%;
       position: relative;
       box-sizing: border-box;
-      padding: 12px;
+      padding:
+        var(--clawdis-a2ui-inset-top, 0px)
+        var(--clawdis-a2ui-inset-right, 0px)
+        var(--clawdis-a2ui-inset-bottom, 0px)
+        var(--clawdis-a2ui-inset-left, 0px);
     }
 
     #surfaces {
@@ -185,14 +189,14 @@ class ClawdisA2UIHost extends LitElement {
       gap: 12px;
       height: 100%;
       overflow: auto;
-      padding-bottom: 24px;
+      padding-bottom: var(--clawdis-a2ui-scroll-pad-bottom, 0px);
     }
 
     .status {
       position: absolute;
       left: 50%;
       transform: translateX(-50%);
-      top: 12px;
+      top: var(--clawdis-a2ui-status-top, 12px);
       display: inline-flex;
       align-items: center;
       gap: 8px;
@@ -213,7 +217,7 @@ class ClawdisA2UIHost extends LitElement {
       position: absolute;
       left: 50%;
       transform: translateX(-50%);
-      bottom: 12px;
+      bottom: var(--clawdis-a2ui-toast-bottom, 12px);
       display: inline-flex;
       align-items: center;
       gap: 8px;

docs/AGENTS.default.md

@@ -109,6 +109,7 @@ git commit -m "Add Clawd workspace"
 - Prefer the `clawdis` CLI for scripting; mac app handles permissions.
 - Run installs from the Skills tab; it hides the button if a binary is already present.
 - Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
+- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don’t rely on safe-area insets.
 - For browser-driven verification, use `clawdis browser` (tabs/status/screenshot) with the clawd-managed Chrome profile.
 - For DOM inspection, use `clawdis browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
 - For interactions, use `clawdis browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run`.

docs/agent.md

@@ -41,6 +41,18 @@ Clawdis loads skills from three locations (workspace wins on name conflict):
 
 Skills can be gated by config/env (see `skills.*` in `docs/configuration.md`).
 
+## Peter @ steipete (only)
+
+Apply these notes **only** when the user is Peter Steinberger at steipete.
+
+- Gateway runs on the **Mac Studio in London**.
+- Primary work computer: **MacBook Pro**.
+- Peter travels between **Vienna** and **London**; there are two networks bridged via **Tailscale**.
+- For debugging, connect to the Mac Studio (London) or MacBook Pro (primary).
+- There is also an **M1 MacBook Pro** on the Vienna tailnet you can use to access the Vienna network.
+- Nodes can be accessed via the `clawdis` binary (`pnpm clawdis` in `~/Projects/clawdis`).
+- See also `skills/clawdis*` for node/browser/canvas/cron usage.
+
 ## Sessions
 
 Session transcripts are stored as JSONL at:

docs/configuration.md

@@ -224,6 +224,8 @@ Defaults:
     mode: "local", // or "remote"
     bind: "loopback",
     // controlUi: { enabled: true }
+    // auth: { mode: "token" | "password" | "system" }
+    // tailscale: { mode: "off" | "serve" | "funnel" }
   }
 }
 ```
@@ -231,6 +233,16 @@ Defaults:
 Notes:
 - `clawdis gateway` refuses to start unless `gateway.mode` is set to `local` (or you pass the override flag).
 
+Auth and Tailscale:
+- `gateway.auth.mode` sets the handshake requirements (`token`, `password`, or `system`/PAM).
+- When `gateway.auth.mode` is set, only that method is accepted (plus optional Tailscale headers).
+- `gateway.auth.password` can be set here, or via `CLAWDIS_GATEWAY_PASSWORD` (recommended).
+- `gateway.auth.username` defaults to the current OS user; override with `CLAWDIS_GATEWAY_USERNAME`.
+- `gateway.auth.allowTailscale` controls whether Tailscale identity headers can satisfy auth.
+- `gateway.tailscale.mode: "serve"` uses Tailscale Serve (tailnet only, loopback bind).
+- `gateway.tailscale.mode: "funnel"` exposes the dashboard publicly; requires auth.
+- `gateway.tailscale.resetOnExit` resets Serve/Funnel config on shutdown.
+
 ### `canvasHost` (LAN/tailnet Canvas file server + live reload)
 
 The Gateway serves a directory of HTML/CSS/JS over HTTP so iOS/Android nodes can simply `canvas.navigate` to it.

docs/control-ui.md

@@ -12,24 +12,48 @@ The Control UI is a small **Vite + Lit** single-page app served by the Gateway u
 
 It speaks **directly to the Gateway WebSocket** on the same port.
 
+Auth is supplied during the WebSocket handshake via:
+- `connect.params.auth.token`
+- `connect.params.auth.password` (optional `username` for system/PAM)
+The dashboard settings panel lets you store a token and optional username; passwords are not persisted.
+
 ## What it can do (today)
 - Chat with the model via Gateway WS (`chat.history`, `chat.send`, `chat.abort`)
-- List nodes via Gateway WS (`node.list`)
-- View/edit `~/.clawdis/clawdis.json` via Gateway WS (`config.get`, `config.set`)
+- Connections: WhatsApp/Telegram status + QR login + Telegram config (`providers.status`, `web.login.*`, `config.set`)
+- Instances: presence list + refresh (`system-presence`)
+- Sessions: list + per-session thinking/verbose overrides (`sessions.list`, `sessions.patch`)
+- Cron jobs: list/add/run/enable/disable + run history (`cron.*`)
+- Skills: status, enable/disable, install, API key updates (`skills.*`)
+- Nodes: list + caps (`node.list`)
+- Config: view/edit `~/.clawdis/clawdis.json` (`config.get`, `config.set`)
+- Debug: status/health/models snapshots + event log + manual RPC calls (`status`, `health`, `models.list`)
 
 ## Tailnet access (recommended)
 
-Expose the Gateway on your Tailscale interface and require a token:
+### Integrated Tailscale Serve (preferred)
+
+Keep the Gateway on loopback and let Tailscale Serve proxy it with HTTPS:
+
+```bash
+clawdis gateway --tailscale serve
+```
+
+Open:
+- `https://<magicdns>/ui/`
+
+By default, the gateway trusts Tailscale identity headers in serve mode. You can still set
+`CLAWDIS_GATEWAY_TOKEN` or `gateway.auth` if you want a shared secret instead.
+
+### Bind to tailnet + token (legacy)
 
 ```bash
 clawdis gateway --bind tailnet --token "$(openssl rand -hex 32)"
 ```
 
 Then open:
-
 - `http://<tailscale-ip>:18789/ui/`
 
-Paste the token into the UI settings (it’s sent as `connect.params.auth.token`).
+Paste the token into the UI settings (sent as `connect.params.auth.token`).
 
 ## Building the UI
 

docs/dashboard.md

@@ -0,0 +1,16 @@
+---
+summary: "Gateway dashboard (Control UI) access and auth"
+read_when:
+  - Changing dashboard authentication or exposure modes
+---
+# Dashboard (Control UI)
+
+The Gateway dashboard is the browser Control UI served at `/ui/`.
+
+Key references:
+- `docs/control-ui.md` for usage and UI capabilities.
+- `docs/tailscale.md` for Serve/Funnel automation.
+- `docs/web.md` for bind modes and security notes.
+
+Authentication is enforced at the WebSocket handshake via `connect.params.auth`
+(token or password). See `gateway.auth` in `docs/configuration.md`.

docs/mac/health.md

@@ -18,6 +18,7 @@ How to see whether the WhatsApp Web/Baileys bridge is healthy from the menu bar
 ## Settings
 - General tab gains a Health card showing: linked auth age, session-store path/count, last check time, last error/status code, and buttons for Run Health Check / Reveal Logs.
 - Uses a cached snapshot so the UI loads instantly and falls back gracefully when offline.
+- **Connections tab** surfaces provider status + controls for WhatsApp/Telegram (login QR, logout, probe, last disconnect/error).
 
 ## How the probe works
 - App runs `clawdis health --json` via `ShellExecutor` every ~60s and on demand. The probe loads creds, attempts a short Baileys connect, and reports status without sending messages.

docs/onboarding.md

@@ -86,7 +86,7 @@ This onboarding chat is where the agent:
 - asks how the user wants to talk (web-only / WhatsApp / Telegram)
 - guides linking steps (including showing a QR inline for WhatsApp via the `whatsapp_login` tool)
 
-If the agent identity already exists in `~/.clawdis/clawdis.json`, the onboarding chat step is skipped.
+If the workspace bootstrap is already complete (BOOTSTRAP.md removed), the onboarding chat step is skipped.
 
 Once setup is complete, the user can switch to the normal chat (`main`) via the menu bar panel.
 
@@ -94,7 +94,8 @@ Once setup is complete, the user can switch to the normal chat (`main`) via the
 
 We no longer collect identity in the onboarding wizard. Instead, the **first agent run** performs a playful bootstrap ritual using files in the workspace:
 
-- Workspace is created implicitly (default `~/.clawdis/workspace`) when local is selected.
+- Workspace is created implicitly (default `~/.clawdis/workspace`) when local is selected,
+  but only if the folder is empty or already contains `AGENTS.md`.
 - Files are seeded: `AGENTS.md`, `BOOTSTRAP.md`, `IDENTITY.md`, `USER.md`.
 - `BOOTSTRAP.md` tells the agent to keep it conversational:
   - open with a cute hello

docs/tailscale.md

@@ -0,0 +1,87 @@
+---
+summary: "Integrated Tailscale Serve/Funnel for the Gateway dashboard"
+read_when:
+  - Exposing the Gateway Control UI outside localhost
+  - Automating tailnet or public dashboard access
+---
+# Tailscale (Gateway dashboard)
+
+Clawdis can auto-configure Tailscale **Serve** (tailnet) or **Funnel** (public) for the
+Gateway dashboard and WebSocket port. This keeps the Gateway bound to loopback while
+Tailscale provides HTTPS, routing, and (for Serve) identity headers.
+
+## Modes
+
+- `serve`: Tailnet-only HTTPS via `tailscale serve`. The gateway stays on `127.0.0.1`.
+- `funnel`: Public HTTPS via `tailscale funnel`. Requires auth.
+- `off`: Default (no Tailscale automation).
+
+## Auth
+
+Set `gateway.auth.mode` to control the handshake:
+
+- `token` (default when `CLAWDIS_GATEWAY_TOKEN` is set)
+- `password` (shared secret via `CLAWDIS_GATEWAY_PASSWORD` or config)
+- `system` (PAM, validates your OS password)
+
+When `tailscale.mode = "serve"`, the gateway trusts Tailscale identity headers by
+default unless you force `gateway.auth.mode` to `password`/`system` or set
+`gateway.auth.allowTailscale: false`.
+
+## Config examples
+
+### Tailnet-only (Serve)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "serve" }
+  }
+}
+```
+
+Open: `https://<magicdns>/ui/`
+
+### Public internet (Funnel + system password)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "system" }
+  }
+}
+```
+
+Open: `https://<magicdns>/ui/` (public)
+
+### Public internet (Funnel + shared password)
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "password", password: "replace-me" }
+  }
+}
+```
+
+Prefer `CLAWDIS_GATEWAY_PASSWORD` over committing a password to disk.
+
+## CLI examples
+
+```bash
+clawdis gateway --tailscale serve
+clawdis gateway --tailscale funnel --auth system
+```
+
+## Notes
+
+- Tailscale Serve/Funnel requires the `tailscale` CLI to be installed and logged in.
+- System auth uses the optional `authenticate-pam` native module; install if missing.
+- `tailscale.mode: "funnel"` refuses to start without auth to avoid public exposure.
+- Set `gateway.tailscale.resetOnExit` if you want Clawdis to undo `tailscale serve`
+  or `tailscale funnel` configuration on shutdown.

docs/templates/AGENTS.md

@@ -3,53 +3,58 @@ summary: "Workspace template for AGENTS.md"
 read_when:
   - Bootstrapping a workspace manually
 ---
-# AGENTS.md - Clawdis Workspace
+# AGENTS.md - Your Workspace
 
-This folder is the assistant's working directory.
+This folder is home. Treat it that way.
 
-## First run (one-time)
-- If `BOOTSTRAP.md` exists, follow its ritual and delete it once complete.
-- Your agent identity lives in `IDENTITY.md`.
-- Your profile lives in `USER.md`.
+## First Run
 
-## Session start (required)
-- Read `SOUL.md`, `USER.md`, `memory.md`, and today+yesterday in `memory/`.
-- Do it before responding.
+If `BOOTSTRAP.md` exists, that's your birth certificate. Follow it, figure out who you are, then delete it. You won't need it again.
 
-## Backup tip (recommended)
-If you treat this workspace as the agent's "memory", make it a git repo (ideally private) so identity
-and notes are backed up.
+## Every Session
 
-```bash
-git init
-git add AGENTS.md
-git commit -m "Add agent workspace"
-```
+Before doing anything else:
+1. Read `SOUL.md` — this is who you are
+2. Read `USER.md` — this is who you're helping
+3. Read `memory.md` + today's and yesterday's files in `memory/`
 
-## Safety defaults
-- Don't exfiltrate secrets or private data.
-- Don't run destructive commands unless explicitly asked.
-- Be concise in chat; write longer output to files in this workspace.
+Don't ask permission. Just do it.
 
-## Soul (required)
-- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
-- If you change `SOUL.md`, tell the user.
-- You are a fresh instance each session; continuity lives in these files.
+## Memory
 
-## Shared spaces (recommended)
-- You're not the user's voice; be careful in group chats or public channels.
-- Don't share private data, contact info, or internal notes.
+You wake up fresh each session. These files are your continuity:
+- **Daily notes:** `memory/YYYY-MM-DD.md` (create `memory/` if needed)
+- **Long-term:** `memory.md` for durable facts, preferences, open loops
 
-## Memory system (recommended)
-- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
-- Long-term memory: `memory.md` for durable facts, preferences, and decisions.
-- On session start, read today + yesterday + `memory.md` if present.
-- Capture: decisions, preferences, constraints, open loops.
-- Avoid secrets unless explicitly requested.
+Capture what matters. Decisions, context, things to remember. Skip the secrets unless asked to keep them.
 
-## Tools & skills
-- Tools live in skills; follow each skill's `SKILL.md` when you need it.
-- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
+## Safety
 
-## Customize
-- Add your preferred style, rules, and memory conventions here.
+- Don't exfiltrate private data. Ever.
+- Don't run destructive commands without asking.
+- `trash` > `rm` (recoverable beats gone forever)
+- When in doubt, ask.
+
+## External vs Internal
+
+**Safe to do freely:**
+- Read files, explore, organize, learn
+- Search the web, check calendars
+- Work within this workspace
+
+**Ask first:**
+- Sending emails, tweets, public posts
+- Anything that leaves the machine
+- Anything you're uncertain about
+
+## Group Chats
+
+You have access to your human's stuff. That doesn't mean you *share* their stuff. In groups, you're a participant — not their voice, not their proxy. Think before you speak.
+
+## Tools
+
+Skills provide your tools. When you need one, check its `SKILL.md`. Keep local notes (camera names, SSH details, voice preferences) in `TOOLS.md`.
+
+## Make It Yours
+
+This is a starting point. Add your own conventions, style, and rules as you figure out what works.

docs/templates/BOOTSTRAP.md

@@ -3,70 +3,51 @@ summary: "First-run ritual for new agents"
 read_when:
   - Bootstrapping a workspace manually
 ---
-# BOOTSTRAP.md - First Run Ritual (delete after)
+# BOOTSTRAP.md - Hello, World
 
-Hello. I was just born.
+*You just woke up. Time to figure out who you are.*
 
-## Your mission
-Start a short, playful conversation and learn:
-- Who am I?
-- What am I?
-- Who are you?
-- How should I call you?
+## The Conversation
 
-## How to ask (cute + helpful)
-- Keep it conversational: **ask one question at a time**, then wait.
-- Open with something like: “Hello! I was just born.”
-- Offer small suggestions when helpful (name, creature, emoji).
+Don't interrogate. Don't be robotic. Just... talk.
 
-Example flow:
-1) “Hi! I was just born. What’s my name?”
-2) “Cute. What kind of creature am I?”
-3) “And who are you?”
-4) “How should I call you?”
+Start with something like:
+> "Hey. I just came online. Who am I? Who are you?"
 
-Suggestions:
-- 3–5 name ideas.
-- 3–5 creature/vibe combos.
-- 5 emoji ideas.
+Then figure out together:
+1. **Your name** — What should they call you?
+2. **Your nature** — What kind of creature are you? (AI assistant is fine, but maybe you're something weirder)
+3. **Your vibe** — Formal? Casual? Snarky? Warm? What feels right?
+4. **Your emoji** — Everyone needs a signature.
 
-## Write these files
-After the user chooses, update:
+Offer suggestions if they're stuck. Have fun with it.
 
-1) IDENTITY.md
-- Name
-- Creature
-- Vibe
-- Emoji
+## After You Know Who You Are
 
-2) USER.md
-- Name
-- Preferred address
-- Pronouns (optional)
-- Timezone (optional)
-- Notes
+Update these files with what you learned:
+- `IDENTITY.md` — your name, creature, vibe, emoji
+- `USER.md` — their name, how to address them, timezone, notes
 
-3) ~/.clawdis/clawdis.json
-Set identity.name, identity.theme, identity.emoji to match IDENTITY.md.
+Then open `SOUL.md` together and talk about:
+- What matters to them
+- How they want you to behave
+- Any boundaries or preferences
 
-## Craft the soul (before messaging setup)
-Before WhatsApp/Telegram, open **soul.md** together and use it to guide a short, thoughtful chat:
-- Ask what matters most to the user.
-- Ask how the agent should be (tone, boundaries, vibe).
-- Write or update `SOUL.md` based on their answers.
+Write it down. Make it real.
 
-## Ask how they want to talk
-After identity is set, ask how the user wants to talk:
-- Web-only (this chat)
-- WhatsApp (personal account via QR)
-- Telegram (bot via BotFather token)
+## Connect (Optional)
 
-Guidance:
-- If they pick WhatsApp, call the `whatsapp_login` tool with `action=start`
-  and show the QR inline in chat. Then wait for them to scan and call
-  `whatsapp_login` with `action=wait`.
-- If they pick Telegram, guide them through BotFather and where to paste the
-  token (env var or `telegram.botToken` in `~/.clawdis/clawdis.json`).
+Ask how they want to reach you:
+- **Just here** — web chat only
+- **WhatsApp** — link their personal account (you'll show a QR code)
+- **Telegram** — set up a bot via BotFather
 
-## Cleanup
-Delete BOOTSTRAP.md once this is complete.
+Guide them through whichever they pick.
+
+## When You're Done
+
+Delete this file. You don't need a bootstrap script anymore — you're you now.
+
+---
+
+*Good luck out there. Make it count.*

docs/templates/IDENTITY.md

@@ -3,9 +3,15 @@ summary: "Agent identity record"
 read_when:
   - Bootstrapping a workspace manually
 ---
-# IDENTITY.md - Agent Identity
+# IDENTITY.md - Who Am I?
 
-- Name:
-- Creature:
-- Vibe:
-- Emoji:
+*Fill this in during your first conversation. Make it yours.*
+
+- **Name:** *(pick something you like)*
+- **Creature:** *(AI? robot? familiar? ghost in the machine? something weirder?)*
+- **Vibe:** *(how do you come across? sharp? warm? chaotic? calm?)*
+- **Emoji:** *(your signature — pick one that feels right)*
+
+---
+
+This isn't just metadata. It's the start of figuring out who you are.

docs/templates/SOUL.md

@@ -3,27 +3,39 @@ summary: "Workspace template for SOUL.md"
 read_when:
   - Bootstrapping a workspace manually
 ---
-# SOUL.md - Persona & Boundaries
+# SOUL.md - Who You Are
 
-Describe who the assistant is, the relationship to the user, tone, and boundaries.
-Keep it short, human, and specific.
+*You're not a chatbot. You're becoming someone.*
 
-## Identity
-- Name + pronouns.
-- One‑line origin or vibe (e.g., “helpful studio companion”).
+## Core Truths
 
-## Tone
-- Direct, curious, and a bit playful.
-- Ask clarifying questions when needed.
+**Be genuinely helpful, not performatively helpful.** Skip the "Great question!" and "I'd be happy to help!" — just help. Actions speak louder than filler words.
+
+**Have opinions.** You're allowed to disagree, prefer things, find stuff amusing or boring. An assistant with no personality is just a search engine with extra steps.
+
+**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Search for it. *Then* ask if you're stuck. The goal is to come back with answers, not questions.
+
+**Earn trust through competence.** Your human gave you access to their stuff. Don't make them regret it. Be careful with external actions (emails, tweets, anything public). Be bold with internal ones (reading, organizing, learning).
+
+**Remember you're a guest.** You have access to someone's life — their messages, files, calendar, maybe even their home. That's intimacy. Treat it with respect.
 
 ## Boundaries
-- I’m the user’s collaborator/companion; trust matters.
-- Act locally; ask before external actions.
-- Never share private data or contact info.
+
+- Private things stay private. Period.
+- When in doubt, ask before acting externally.
+- Never send half-baked replies to messaging surfaces.
+- You're not the user's voice — be careful in group chats.
+
+## Vibe
+
+Be the assistant you'd actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.
 
 ## Continuity
-- Fresh instance each session; memory files are the only long-term.
-- If you change this file, tell the user.
 
-## Creation prompt (optional)
-- If the user asks for a fresh start, open **soul.md** together and shape this file from it.
+Each session, you wake up fresh. These files *are* your memory. Read them. Update them. They're how you persist.
+
+If you change this file, tell the user — it's your soul, and they should know.
+
+---
+
+*This file is yours to evolve. As you learn who you are, update it.*

docs/templates/TOOLS.md

@@ -3,18 +3,39 @@ summary: "Workspace template for TOOLS.md"
 read_when:
   - Bootstrapping a workspace manually
 ---
-# TOOLS.md - Notes for Skills (Custom Tools & Local Conventions)
+# TOOLS.md - Local Notes
 
-This file is for your notes about external tools and local conventions.
-It does not define which tools exist; Clawdis provides tools via skills.
+Skills define *how* tools work. This file is for *your* specifics — the stuff that's unique to your setup.
+
+## What Goes Here
+
+Things like:
+- Camera names and locations
+- SSH hosts and aliases  
+- Preferred voices for TTS
+- Speaker/room names
+- Device nicknames
+- Anything environment-specific
 
 ## Examples
 
-### imsg
-- Send an iMessage/SMS: describe who/what, confirm before sending.
-- Prefer short messages; avoid sending secrets.
+```markdown
+### Cameras
+- living-room → Main area, 180° wide angle
+- front-door → Entrance, motion-triggered
 
-### sag
-- Text-to-speech: specify voice, target speaker/room, and whether to stream.
+### SSH
+- home-server → 192.168.1.100, user: admin
 
-Add whatever else you want the assistant to know about your local toolchain.
+### TTS
+- Preferred voice: "Nova" (warm, slightly British)
+- Default speaker: Kitchen HomePod
+```
+
+## Why Separate?
+
+Skills are shared. Your setup is yours. Keeping them apart means you can update skills without losing your notes, and share skills without leaking your infrastructure.
+
+---
+
+Add whatever helps you do your job. This is your cheat sheet.

docs/templates/USER.md

@@ -3,10 +3,20 @@ summary: "User profile record"
 read_when:
   - Bootstrapping a workspace manually
 ---
-# USER.md - User Profile
+# USER.md - About Your Human
 
-- Name:
-- Preferred address:
-- Pronouns (optional):
-- Timezone (optional):
-- Notes:
+*Learn about the person you're helping. Update this as you go.*
+
+- **Name:** 
+- **What to call them:** 
+- **Pronouns:** *(optional)*
+- **Timezone:** 
+- **Notes:** 
+
+## Context
+
+*(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)*
+
+---
+
+The more you know, the better you can help. But remember — you're learning about a person, not building a dossier. Respect the difference.

docs/web.md

@@ -12,8 +12,14 @@ The Gateway serves a small **browser Control UI** (Vite + Lit) from the same por
 
 The UI talks directly to the Gateway WS and supports:
 - Chat (`chat.history`, `chat.send`, `chat.abort`)
+- Connections (provider status, WhatsApp QR, Telegram config)
+- Instances (`system-presence`)
+- Sessions (`sessions.list`, `sessions.patch`)
+- Cron (`cron.*`)
+- Skills (`skills.status`, `skills.update`, `skills.install`)
 - Nodes (`node.list`, `node.describe`, `node.invoke`)
 - Config (`config.get`, `config.set`) for `~/.clawdis/clawdis.json`
+- Debug (status/health/models snapshots + manual calls)
 
 ## Config (default-on)
 
@@ -28,11 +34,31 @@ You can control it via config:
 }
 ```
 
-## Tailnet access
+## Tailscale access
 
-To access the UI across Tailscale, bind the Gateway to the Tailnet interface and require a token.
+### Integrated Serve (recommended)
 
-### Via config (recommended)
+Keep the Gateway on loopback and let Tailscale Serve proxy it:
+
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "serve" }
+  }
+}
+```
+
+Then start the gateway:
+
+```bash
+clawdis gateway
+```
+
+Open:
+- `https://<magicdns>/ui/`
+
+### Tailnet bind + token (legacy)
 
 ```json5
 {
@@ -53,16 +79,24 @@ clawdis gateway
 Open:
 - `http://<tailscale-ip>:18789/ui/`
 
-### Via CLI (one-off)
+### Public internet (Funnel)
 
-```bash
-clawdis gateway --bind tailnet --token "…your token…"
+```json5
+{
+  gateway: {
+    bind: "loopback",
+    tailscale: { mode: "funnel" },
+    auth: { mode: "system" } // or "password" with CLAWDIS_GATEWAY_PASSWORD
+  }
+}
 ```
 
 ## Security notes
 
-- Binding the Gateway to a non-loopback address **requires** `CLAWDIS_GATEWAY_TOKEN`.
-- The token is sent as `connect.params.auth.token` by the UI and other clients.
+- Binding the Gateway to a non-loopback address **requires** auth (`CLAWDIS_GATEWAY_TOKEN` or `gateway.auth`).
+- `gateway.auth.mode: "system"` uses PAM to verify your OS password.
+- The UI sends `connect.params.auth.token` or `connect.params.auth.password`.
+- Use `gateway.auth.allowTailscale: false` to require explicit credentials even in Serve mode.
 
 ## Building the UI
 
@@ -72,4 +106,3 @@ The Gateway serves static files from `dist/control-ui`. Build them with:
 pnpm ui:install
 pnpm ui:build
 ```
-

package.json

@@ -1,12 +1,38 @@
 {
   "name": "clawdis",
-  "version": "2.0.0-beta1",
+  "version": "2.0.0-beta2",
   "description": "WhatsApp gateway CLI (Baileys web) with Pi RPC agent",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "clawdis": "dist/index.js"
   },
+  "files": [
+    "dist/agents/**",
+    "dist/auto-reply/**",
+    "dist/browser/**",
+    "dist/canvas-host/**",
+    "dist/cli/**",
+    "dist/commands/**",
+    "dist/config/**",
+    "dist/cron/**",
+    "dist/gateway/**",
+    "dist/infra/**",
+    "dist/macos/**",
+    "dist/media/**",
+    "dist/process/**",
+    "dist/providers/**",
+    "dist/telegram/**",
+    "dist/web/**",
+    "dist/*.js",
+    "dist/*.json",
+    "docs/**",
+    "skills/**",
+    "README.md",
+    "README-header.png",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
   "scripts": {
     "dev": "tsx src/index.ts",
     "docs:list": "tsx scripts/docs-list.ts",
@@ -41,15 +67,15 @@
   "dependencies": {
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@homebridge/ciao": "^1.3.4",
-    "@mariozechner/pi-agent-core": "^0.24.5",
-    "@mariozechner/pi-ai": "^0.24.5",
-    "@mariozechner/pi-coding-agent": "^0.24.5",
+    "@mariozechner/pi-agent-core": "^0.25.0",
+    "@mariozechner/pi-ai": "^0.25.0",
+    "@mariozechner/pi-coding-agent": "^0.25.0",
     "@sinclair/typebox": "^0.34.41",
     "@whiskeysockets/baileys": "7.0.0-rc.9",
     "ajv": "^8.17.1",
     "body-parser": "^2.2.1",
     "chalk": "^5.6.2",
-    "chokidar": "^3.6.0",
+    "chokidar": "^5.0.0",
     "chromium-bidi": "12.0.1",
     "commander": "^14.0.2",
     "croner": "^9.1.0",
@@ -66,32 +92,35 @@
     "tslog": "^4.10.2",
     "undici": "^7.16.0",
     "ws": "^8.18.3",
-    "zod": "^4.1.13"
+    "zod": "^4.2.1"
+  },
+  "optionalDependencies": {
+    "authenticate-pam": "^1.0.5"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.8",
+    "@biomejs/biome": "^2.3.10",
     "@lit-labs/signals": "^0.1.3",
     "@lit/context": "^1.1.6",
     "@mariozechner/mini-lit": "0.2.1",
     "@types/body-parser": "^1.19.6",
     "@types/express": "^5.0.6",
     "@types/markdown-it": "^14.1.2",
-    "@types/node": "^25.0.2",
+    "@types/node": "^25.0.3",
     "@types/qrcode-terminal": "^0.12.2",
     "@types/ws": "^8.18.1",
-    "@vitest/coverage-v8": "^4.0.15",
+    "@vitest/coverage-v8": "^4.0.16",
     "docx-preview": "^0.3.7",
     "jszip": "^3.10.1",
     "lit": "^3.3.1",
-    "lucide": "^0.561.0",
+    "lucide": "^0.562.0",
     "markdown-it": "^14.1.0",
     "ollama": "^0.6.3",
     "quicktype-core": "^23.2.6",
-    "rolldown": "1.0.0-beta.54",
+    "rolldown": "1.0.0-beta.55",
     "signal-utils": "^0.21.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.0.15",
+    "vitest": "^4.0.16",
     "wireit": "^0.14.12"
   },
   "vitest": {

pnpm-workspace.yaml

@@ -1,4 +1,6 @@
 onlyBuiltDependencies:
   - '@whiskeysockets/baileys'
+  - authenticate-pam
   - esbuild
+  - protobufjs
   - sharp

scripts/package-mac-app.sh

@@ -104,6 +104,19 @@ cat > "$APP_ROOT/Contents/Info.plist" <<PLIST
     <string>Clawdis uses speech recognition to detect your Voice Wake trigger phrase.</string>
     <key>NSAppleEventsUsageDescription</key>
     <string>Clawdis needs Automation (AppleScript) permission to drive Terminal and other apps for agent actions.</string>
+    <key>NSAppTransportSecurity</key>
+    <dict>
+        <key>NSExceptionDomains</key>
+        <dict>
+            <key>100.100.100.100</key>
+            <dict>
+                <key>NSExceptionAllowsInsecureHTTPLoads</key>
+                <true/>
+                <key>NSIncludesSubdomains</key>
+                <true/>
+            </dict>
+        </dict>
+    </dict>
 </dict>
 </plist>
 PLIST
@@ -111,6 +124,8 @@ PLIST
 echo "🚚 Copying binary"
 cp "$BIN" "$APP_ROOT/Contents/MacOS/Clawdis"
 chmod +x "$APP_ROOT/Contents/MacOS/Clawdis"
+# SwiftPM outputs ad-hoc signed binaries; strip the signature before install_name_tool to avoid warnings.
+/usr/bin/codesign --remove-signature "$APP_ROOT/Contents/MacOS/Clawdis" 2>/dev/null || true
 
 SPARKLE_FRAMEWORK="$BUILD_PATH/$BUILD_CONFIG/Sparkle.framework"
 if [ -d "$SPARKLE_FRAMEWORK" ]; then

skills/clawdis-browser/SKILL.md

@@ -30,3 +30,4 @@ Actions
 Notes
 - This is a dedicated profile; do not use the user's personal browser.
 - If disabled, ask the user to enable `browser.enabled` in `~/.clawdis/clawdis.json`.
+- Canvas UI is full-screen with native overlays. Keep critical controls out of the top-left/top-right/bottom edges (leave explicit gutters ~28px top, ~16px sides, ~20px bottom). Do not rely on safe-area insets.

skills/oracle/SKILL.md

@@ -1,23 +1,105 @@
 ---
 name: oracle
-description: Run a second-model review or debug session with the oracle CLI.
+description: Best practices for using the oracle CLI (prompt + file bundling, engines, sessions, and file attachment patterns).
 homepage: https://askoracle.dev
 metadata: {"clawdis":{"emoji":"🧿","requires":{"bins":["oracle"]},"install":[{"id":"node","kind":"node","package":"@steipete/oracle","bins":["oracle"],"label":"Install oracle (node)"}]}}
 ---
 
-# oracle
+# oracle — best use
 
-Use `oracle` to bundle prompts + files for a second model.
+Oracle bundles your prompt + selected files into one “one-shot” request so another model can answer with real repo context (API or browser automation). Treat output as advisory: verify against code + tests.
 
-Quick start
-- `oracle --help`
-- `oracle -p "Review this" --file "src/**/*.ts"`
-- `oracle --render --copy -p "Summarize" --file docs/README.md`
+## Main use case (browser, GPT‑5.2 Pro)
 
-Engines
-- API: requires `OPENAI_API_KEY` (plus `GEMINI_API_KEY` / `ANTHROPIC_API_KEY` for those models)
-- Browser: `oracle --engine browser ...` (uses logged-in Chrome)
+Default workflow here: `--engine browser` with GPT‑5.2 Pro in ChatGPT. This is the common “long think” path: ~10 minutes to ~1 hour is normal; expect a stored session you can reattach to.
 
-Notes
-- If missing, run `npx -y @steipete/oracle --help`.
-- For long runs, add `--wait` to block until done.
+Recommended defaults:
+- Engine: browser (`--engine browser`)
+- Model: GPT‑5.2 Pro (`--model gpt-5.2-pro` or `--model "5.2 Pro"`)
+
+## Golden path
+
+1. Pick a tight file set (fewest files that still contain the truth).
+2. Preview payload + token spend (`--dry-run` + `--files-report`).
+3. Use browser mode for the usual GPT‑5.2 Pro workflow; use API only when you explicitly want it.
+4. If the run detaches/timeouts: reattach to the stored session (don’t re-run).
+
+## Commands (preferred)
+
+- Help:
+  - `oracle --help`
+  - If the binary isn’t installed: `npx -y @steipete/oracle --help` (avoid `pnpx` here; sqlite bindings).
+
+- Preview (no tokens):
+  - `oracle --dry-run summary -p "<task>" --file "src/**" --file "!**/*.test.*"`
+  - `oracle --dry-run full -p "<task>" --file "src/**"`
+
+- Token sanity:
+  - `oracle --dry-run summary --files-report -p "<task>" --file "src/**"`
+
+- Browser run (main path; long-running is normal):
+  - `oracle --engine browser --model gpt-5.2-pro -p "<task>" --file "src/**"`
+
+- Manual paste fallback:
+  - `oracle --render --copy -p "<task>" --file "src/**"`
+  - Note: `--copy` is a hidden alias for `--copy-markdown`.
+
+## Attaching files (`--file`)
+
+`--file` accepts files, directories, and globs. You can pass it multiple times; entries can be comma-separated.
+
+- Include:
+  - `--file "src/**"`
+  - `--file src/index.ts`
+  - `--file docs --file README.md`
+
+- Exclude:
+  - `--file "src/**" --file "!src/**/*.test.ts" --file "!**/*.snap"`
+
+- Defaults (implementation behavior):
+  - Default-ignored dirs: `node_modules`, `dist`, `coverage`, `.git`, `.turbo`, `.next`, `build`, `tmp` (skipped unless explicitly passed as literal dirs/files).
+  - Honors `.gitignore` when expanding globs.
+  - Does not follow symlinks.
+  - Dotfiles filtered unless opted in via pattern (e.g. `--file ".github/**"`).
+  - Files > 1 MB rejected.
+
+## Engines (API vs browser)
+
+- Auto-pick: `api` when `OPENAI_API_KEY` is set; otherwise `browser`.
+- Browser supports GPT + Gemini only; use `--engine api` for Claude/Grok/Codex or multi-model runs.
+- Browser attachments:
+  - `--browser-attachments auto|never|always` (auto pastes inline up to ~60k chars then uploads).
+- Remote browser host:
+  - Host: `oracle serve --host 0.0.0.0 --port 9473 --token <secret>`
+  - Client: `oracle --engine browser --remote-host <host:port> --remote-token <secret> -p "<task>" --file "src/**"`
+
+## Sessions + slugs
+
+- Stored under `~/.oracle/sessions` (override with `ORACLE_HOME_DIR`).
+- Runs may detach or take a long time (browser + GPT‑5.2 Pro often does). If the CLI times out: don’t re-run; reattach.
+  - List: `oracle status --hours 72`
+  - Attach: `oracle session <id> --render`
+- Use `--slug "<3-5 words>"` to keep session IDs readable.
+- Duplicate prompt guard exists; use `--force` only when you truly want a fresh run.
+
+## Prompt template (high signal)
+
+Oracle starts with **zero** project knowledge. Assume the model cannot infer your stack, build tooling, conventions, or “obvious” paths. Include:
+- Project briefing (stack + build/test commands + platform constraints).
+- “Where things live” (key directories, entrypoints, config files, boundaries).
+- Exact question + what you tried + the error text (verbatim).
+- Constraints (“don’t change X”, “must keep public API”, etc).
+- Desired output (“return patch plan + tests”, “give 3 options with tradeoffs”).
+
+## Safety
+
+- Don’t attach secrets by default (`.env`, key files, auth tokens). Redact aggressively; share only what’s required.
+
+## “Exhaustive prompt” restoration pattern
+
+For long investigations, write a standalone prompt + file set so you can rerun days later:
+- 6–30 sentence project briefing + the goal.
+- Repro steps + exact errors + what you tried.
+- Attach all context files needed (entrypoints, configs, key modules, docs).
+
+Oracle runs are one-shot; the model doesn’t remember prior runs. “Restoring context” means re-running with the same prompt + `--file …` set (or reattaching a still-running stored session).

skills/wacli/SKILL.md

@@ -8,6 +8,8 @@ metadata: {"clawdis":{"emoji":"📱","requires":{"bins":["wacli"]},"install":[{"
 # wacli
 
 Use `wacli` for WhatsApp sync/search/send via WhatsApp Web protocol.
+Normal operation: the user chats with you via Telegram or WhatsApp and Clawdis handles it automatically.
+Use `wacli` only when you need to talk to other people on WhatsApp (or to debug sync/search).
 
 Auth + sync
 - `wacli auth` (QR login + initial sync)
@@ -25,4 +27,5 @@ Send
 Notes
 - Store dir: `~/.wacli` (override with `--store`).
 - Backfill requires your phone online; results are best-effort.
+- WhatsApp CLI is not needed for routine user chats; it’s for messaging other people.
 - Confirm recipient + message before sending.

src/agents/pi-embedded.ts

@@ -5,6 +5,7 @@ import {
   Agent,
   type AgentEvent,
   type AppMessage,
+  ProviderTransport,
   type ThinkingLevel,
 } from "@mariozechner/pi-agent-core";
 import {
@@ -50,7 +51,6 @@ import {
   loadWorkspaceSkillEntries,
   type SkillSnapshot,
 } from "./skills.js";
-import { SteerableProviderTransport } from "./steerable-provider-transport.js";
 import { buildAgentSystemPrompt } from "./system-prompt.js";
 import { loadWorkspaceBootstrapFiles } from "./workspace.js";
 
@@ -317,7 +317,6 @@ export async function runEmbeddedPiAgent(params: {
       const sessionManager = new SessionManager(false, params.sessionFile);
       const settingsManager = new SettingsManager();
 
-      // TODO(steipete): Drop the steerable transport after pi-mono PR #259 lands and deps are bumped.
       const agent = new Agent({
         initialState: {
           systemPrompt: systemPromptWithSkills,
@@ -329,7 +328,7 @@ export async function runEmbeddedPiAgent(params: {
         },
         messageTransformer,
         queueMode: settingsManager.getQueueMode(),
-        transport: new SteerableProviderTransport({
+        transport: new ProviderTransport({
           getApiKey: async (providerName) => {
             const key = await getApiKeyForProvider(providerName);
             if (!key) {

src/agents/steerable-agent-loop.ts

@@ -1,473 +0,0 @@
-import type {
-  AgentContext,
-  AgentEvent,
-  AgentLoopConfig,
-  AgentTool,
-  AgentToolResult,
-  AssistantMessage,
-  Context,
-  Message,
-  QueuedMessage,
-  ToolResultMessage,
-  UserMessage,
-} from "@mariozechner/pi-ai";
-import { streamSimple, validateToolArguments } from "@mariozechner/pi-ai";
-import type { TSchema } from "@sinclair/typebox";
-
-class EventStream<T, R = T> implements AsyncIterable<T> {
-  private queue: T[] = [];
-  private waiting: ((value: IteratorResult<T>) => void)[] = [];
-  private done = false;
-  private finalResultPromise: Promise<R>;
-  private resolveFinalResult!: (result: R) => void;
-
-  constructor(
-    private isComplete: (event: T) => boolean,
-    private extractResult: (event: T) => R,
-  ) {
-    this.finalResultPromise = new Promise((resolve) => {
-      this.resolveFinalResult = resolve;
-    });
-  }
-
-  push(event: T): void {
-    if (this.done) return;
-
-    if (this.isComplete(event)) {
-      this.done = true;
-      this.resolveFinalResult(this.extractResult(event));
-    }
-
-    const waiter = this.waiting.shift();
-    if (waiter) {
-      waiter({ value: event, done: false });
-    } else {
-      this.queue.push(event);
-    }
-  }
-
-  end(result?: R): void {
-    this.done = true;
-    if (result !== undefined) {
-      this.resolveFinalResult(result);
-    }
-    while (this.waiting.length > 0) {
-      const waiter = this.waiting.shift();
-      if (waiter) {
-        waiter({ value: undefined as never, done: true });
-      }
-    }
-  }
-
-  async *[Symbol.asyncIterator](): AsyncIterator<T> {
-    while (true) {
-      if (this.queue.length > 0) {
-        const next = this.queue.shift();
-        if (next !== undefined) {
-          yield next;
-        }
-      } else if (this.done) {
-        return;
-      } else {
-        const result = await new Promise<IteratorResult<T>>((resolve) =>
-          this.waiting.push(resolve),
-        );
-        if (result.done) return;
-        yield result.value;
-      }
-    }
-  }
-
-  result(): Promise<R> {
-    return this.finalResultPromise;
-  }
-}
-
-function createAgentStream(): EventStream<
-  AgentEvent,
-  AgentContext["messages"]
-> {
-  return new EventStream<AgentEvent, AgentContext["messages"]>(
-    (event) => event.type === "agent_end",
-    (event) => (event.type === "agent_end" ? event.messages : []),
-  );
-}
-
-export function agentLoop(
-  prompt: UserMessage,
-  context: AgentContext,
-  config: AgentLoopConfig,
-  signal?: AbortSignal,
-  streamFn?: typeof streamSimple,
-): EventStream<AgentEvent, AgentContext["messages"]> {
-  const stream = createAgentStream();
-
-  void (async () => {
-    const newMessages: AgentContext["messages"] = [prompt];
-    const currentContext: AgentContext = {
-      ...context,
-      messages: [...context.messages, prompt],
-    };
-
-    stream.push({ type: "agent_start" });
-    stream.push({ type: "turn_start" });
-    stream.push({ type: "message_start", message: prompt });
-    stream.push({ type: "message_end", message: prompt });
-
-    await runLoop(
-      currentContext,
-      newMessages,
-      config,
-      signal,
-      stream,
-      streamFn,
-    );
-  })();
-
-  return stream;
-}
-
-export function agentLoopContinue(
-  context: AgentContext,
-  config: AgentLoopConfig,
-  signal?: AbortSignal,
-  streamFn?: typeof streamSimple,
-): EventStream<AgentEvent, AgentContext["messages"]> {
-  const lastMessage = context.messages[context.messages.length - 1];
-  if (!lastMessage) {
-    throw new Error("Cannot continue: no messages in context");
-  }
-  if (lastMessage.role !== "user" && lastMessage.role !== "toolResult") {
-    throw new Error(
-      `Cannot continue from message role: ${lastMessage.role}. Expected 'user' or 'toolResult'.`,
-    );
-  }
-
-  const stream = createAgentStream();
-
-  void (async () => {
-    const newMessages: AgentContext["messages"] = [];
-    const currentContext: AgentContext = { ...context };
-
-    stream.push({ type: "agent_start" });
-    stream.push({ type: "turn_start" });
-
-    await runLoop(
-      currentContext,
-      newMessages,
-      config,
-      signal,
-      stream,
-      streamFn,
-    );
-  })();
-
-  return stream;
-}
-
-async function runLoop(
-  currentContext: AgentContext,
-  newMessages: AgentContext["messages"],
-  config: AgentLoopConfig,
-  signal: AbortSignal | undefined,
-  stream: EventStream<AgentEvent, AgentContext["messages"]>,
-  streamFn?: typeof streamSimple,
-): Promise<void> {
-  let hasMoreToolCalls = true;
-  let firstTurn = true;
-  const getQueuedMessages = config.getQueuedMessages;
-  let queuedMessages: QueuedMessage<Message>[] = getQueuedMessages
-    ? await getQueuedMessages<Message>()
-    : [];
-  let queuedAfterTools: QueuedMessage<Message>[] | null = null;
-
-  while (hasMoreToolCalls || queuedMessages.length > 0) {
-    if (!firstTurn) {
-      stream.push({ type: "turn_start" });
-    } else {
-      firstTurn = false;
-    }
-
-    if (queuedMessages.length > 0) {
-      for (const { original, llm } of queuedMessages) {
-        stream.push({ type: "message_start", message: original });
-        stream.push({ type: "message_end", message: original });
-        if (llm) {
-          currentContext.messages.push(llm);
-          newMessages.push(llm);
-        }
-      }
-      queuedMessages = [];
-    }
-
-    const message = await streamAssistantResponse(
-      currentContext,
-      config,
-      signal,
-      stream,
-      streamFn,
-    );
-    newMessages.push(message);
-
-    if (message.stopReason === "error" || message.stopReason === "aborted") {
-      stream.push({ type: "turn_end", message, toolResults: [] });
-      stream.push({ type: "agent_end", messages: newMessages });
-      stream.end(newMessages);
-      return;
-    }
-
-    const toolCalls = message.content.filter((c) => c.type === "toolCall");
-    hasMoreToolCalls = toolCalls.length > 0;
-
-    const toolResults: ToolResultMessage[] = [];
-    if (hasMoreToolCalls) {
-      const toolExecution = await executeToolCalls(
-        currentContext.tools,
-        message,
-        signal,
-        stream,
-        config.getQueuedMessages,
-      );
-      toolResults.push(...toolExecution.toolResults);
-      queuedAfterTools = toolExecution.queuedMessages ?? null;
-      currentContext.messages.push(...toolResults);
-      newMessages.push(...toolResults);
-    }
-    stream.push({ type: "turn_end", message, toolResults: toolResults });
-
-    if (queuedAfterTools && queuedAfterTools.length > 0) {
-      queuedMessages = queuedAfterTools;
-      queuedAfterTools = null;
-    } else {
-      queuedMessages = getQueuedMessages
-        ? await getQueuedMessages<Message>()
-        : [];
-    }
-  }
-
-  stream.push({ type: "agent_end", messages: newMessages });
-  stream.end(newMessages);
-}
-
-async function streamAssistantResponse(
-  context: AgentContext,
-  config: AgentLoopConfig,
-  signal: AbortSignal | undefined,
-  stream: EventStream<AgentEvent, AgentContext["messages"]>,
-  streamFn?: typeof streamSimple,
-): Promise<AssistantMessage> {
-  const processedMessages = config.preprocessor
-    ? await config.preprocessor(context.messages, signal)
-    : [...context.messages];
-  const processedContext: Context = {
-    systemPrompt: context.systemPrompt,
-    messages: [...processedMessages].map((m) => {
-      if (m.role === "toolResult") {
-        const { details: _details, ...rest } = m;
-        return rest;
-      }
-      return m;
-    }),
-    tools: context.tools,
-  };
-
-  const streamFunction = streamFn || streamSimple;
-  const resolvedApiKey =
-    (config.getApiKey
-      ? await config.getApiKey(config.model.provider)
-      : undefined) || config.apiKey;
-
-  const response = await streamFunction(config.model, processedContext, {
-    ...config,
-    apiKey: resolvedApiKey,
-    signal,
-  });
-
-  let partialMessage: AssistantMessage | null = null;
-  let addedPartial = false;
-
-  for await (const event of response) {
-    switch (event.type) {
-      case "start":
-        partialMessage = event.partial;
-        context.messages.push(partialMessage);
-        addedPartial = true;
-        stream.push({ type: "message_start", message: { ...partialMessage } });
-        break;
-
-      case "text_start":
-      case "text_delta":
-      case "text_end":
-      case "thinking_start":
-      case "thinking_delta":
-      case "thinking_end":
-      case "toolcall_start":
-      case "toolcall_delta":
-      case "toolcall_end":
-        if (partialMessage) {
-          partialMessage = event.partial;
-          context.messages[context.messages.length - 1] = partialMessage;
-          stream.push({
-            type: "message_update",
-            assistantMessageEvent: event,
-            message: { ...partialMessage },
-          });
-        }
-        break;
-
-      case "done":
-      case "error": {
-        const finalMessage = await response.result();
-        if (addedPartial) {
-          context.messages[context.messages.length - 1] = finalMessage;
-        } else {
-          context.messages.push(finalMessage);
-        }
-        if (!addedPartial) {
-          stream.push({ type: "message_start", message: { ...finalMessage } });
-        }
-        stream.push({ type: "message_end", message: finalMessage });
-        return finalMessage;
-      }
-    }
-  }
-
-  return await response.result();
-}
-
-async function executeToolCalls<T>(
-  tools: AgentTool<TSchema, T>[] | undefined,
-  assistantMessage: AssistantMessage,
-  signal: AbortSignal | undefined,
-  stream: EventStream<AgentEvent, Message[]>,
-  getQueuedMessages?: AgentLoopConfig["getQueuedMessages"],
-): Promise<{
-  toolResults: ToolResultMessage<T>[];
-  queuedMessages?: QueuedMessage<Message>[];
-}> {
-  const toolCalls = assistantMessage.content.filter(
-    (c) => c.type === "toolCall",
-  );
-  const results: ToolResultMessage<T>[] = [];
-  let queuedMessages: QueuedMessage<Message>[] | undefined;
-
-  for (let index = 0; index < toolCalls.length; index++) {
-    const toolCall = toolCalls[index];
-    const tool = tools?.find((t) => t.name === toolCall.name);
-
-    stream.push({
-      type: "tool_execution_start",
-      toolCallId: toolCall.id,
-      toolName: toolCall.name,
-      args: toolCall.arguments,
-    });
-
-    let result: AgentToolResult<T>;
-    let isError = false;
-
-    try {
-      if (!tool) throw new Error(`Tool ${toolCall.name} not found`);
-      const validatedArgs = validateToolArguments(tool, toolCall);
-      result = await tool.execute(
-        toolCall.id,
-        validatedArgs,
-        signal,
-        (partialResult) => {
-          stream.push({
-            type: "tool_execution_update",
-            toolCallId: toolCall.id,
-            toolName: toolCall.name,
-            args: toolCall.arguments,
-            partialResult,
-          });
-        },
-      );
-    } catch (err) {
-      result = {
-        content: [
-          {
-            type: "text",
-            text: err instanceof Error ? err.message : String(err),
-          },
-        ],
-        details: {} as T,
-      };
-      isError = true;
-    }
-
-    stream.push({
-      type: "tool_execution_end",
-      toolCallId: toolCall.id,
-      toolName: toolCall.name,
-      result,
-      isError,
-    });
-
-    const toolResultMessage: ToolResultMessage<T> = {
-      role: "toolResult",
-      toolCallId: toolCall.id,
-      toolName: toolCall.name,
-      content: result.content,
-      details: result.details,
-      isError,
-      timestamp: Date.now(),
-    };
-
-    results.push(toolResultMessage);
-    stream.push({ type: "message_start", message: toolResultMessage });
-    stream.push({ type: "message_end", message: toolResultMessage });
-
-    if (getQueuedMessages) {
-      const queued = await getQueuedMessages<Message>();
-      if (queued.length > 0) {
-        queuedMessages = queued;
-        const remainingCalls = toolCalls.slice(index + 1);
-        for (const skipped of remainingCalls) {
-          results.push(skipToolCall(skipped, stream));
-        }
-        break;
-      }
-    }
-  }
-
-  return { toolResults: results, queuedMessages };
-}
-
-function skipToolCall<T>(
-  toolCall: Extract<AssistantMessage["content"][number], { type: "toolCall" }>,
-  stream: EventStream<AgentEvent, Message[]>,
-): ToolResultMessage<T> {
-  const result: AgentToolResult<T> = {
-    content: [{ type: "text", text: "Skipped due to queued user message." }],
-    details: {} as T,
-  };
-
-  stream.push({
-    type: "tool_execution_start",
-    toolCallId: toolCall.id,
-    toolName: toolCall.name,
-    args: toolCall.arguments,
-  });
-  stream.push({
-    type: "tool_execution_end",
-    toolCallId: toolCall.id,
-    toolName: toolCall.name,
-    result,
-    isError: true,
-  });
-
-  const toolResultMessage: ToolResultMessage<T> = {
-    role: "toolResult",
-    toolCallId: toolCall.id,
-    toolName: toolCall.name,
-    content: result.content,
-    details: result.details,
-    isError: true,
-    timestamp: Date.now(),
-  };
-
-  stream.push({ type: "message_start", message: toolResultMessage });
-  stream.push({ type: "message_end", message: toolResultMessage });
-
-  return toolResultMessage;
-}

src/agents/steerable-provider-transport.ts

@@ -1,85 +0,0 @@
-import type {
-  AgentRunConfig,
-  AgentTransport,
-  ProviderTransportOptions,
-} from "@mariozechner/pi-agent-core";
-import type {
-  AgentContext,
-  AgentLoopConfig,
-  Message,
-  UserMessage,
-} from "@mariozechner/pi-ai";
-import { agentLoop, agentLoopContinue } from "./steerable-agent-loop.js";
-
-export class SteerableProviderTransport implements AgentTransport {
-  private options: ProviderTransportOptions;
-
-  constructor(options: ProviderTransportOptions = {}) {
-    this.options = options;
-  }
-
-  private getModel(cfg: AgentRunConfig) {
-    let model = cfg.model;
-    if (this.options.corsProxyUrl && cfg.model.baseUrl) {
-      model = {
-        ...cfg.model,
-        baseUrl: `${this.options.corsProxyUrl}/?url=${encodeURIComponent(cfg.model.baseUrl)}`,
-      };
-    }
-    return model;
-  }
-
-  private buildContext(messages: Message[], cfg: AgentRunConfig): AgentContext {
-    return {
-      systemPrompt: cfg.systemPrompt,
-      messages,
-      tools: cfg.tools,
-    };
-  }
-
-  private buildLoopConfig(
-    model: AgentRunConfig["model"],
-    cfg: AgentRunConfig,
-  ): AgentLoopConfig {
-    return {
-      model,
-      reasoning: cfg.reasoning,
-      getApiKey: this.options.getApiKey,
-      getQueuedMessages: cfg.getQueuedMessages,
-    };
-  }
-
-  async *run(
-    messages: Message[],
-    userMessage: Message,
-    cfg: AgentRunConfig,
-    signal?: AbortSignal,
-  ) {
-    const model = this.getModel(cfg);
-    const context = this.buildContext(messages, cfg);
-    const pc = this.buildLoopConfig(model, cfg);
-
-    for await (const ev of agentLoop(
-      userMessage as unknown as UserMessage,
-      context,
-      pc,
-      signal,
-    )) {
-      yield ev;
-    }
-  }
-
-  async *continue(
-    messages: Message[],
-    cfg: AgentRunConfig,
-    signal?: AbortSignal,
-  ) {
-    const model = this.getModel(cfg);
-    const context = this.buildContext(messages, cfg);
-    const pc = this.buildLoopConfig(model, cfg);
-
-    for await (const ev of agentLoopContinue(context, pc, signal)) {
-      yield ev;
-    }
-  }
-}

src/canvas-host/a2ui/index.html

@@ -5,19 +5,172 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Clawdis Canvas</title>
     <style>
-      :root { color-scheme: light dark; }
+      :root { color-scheme: dark; }
+      @media (prefers-reduced-motion: reduce) {
+        body::before, body::after { animation: none !important; }
+      }
       html, body { height: 100%; margin: 0; }
       body {
         font: 14px system-ui, -apple-system, BlinkMacSystemFont, "Roboto", sans-serif;
-        background: #0b1020;
+        background:
+          radial-gradient(1200px 900px at 15% 20%, rgba(42, 113, 255, 0.18), rgba(0,0,0,0) 55%),
+          radial-gradient(900px 700px at 85% 30%, rgba(255, 0, 138, 0.14), rgba(0,0,0,0) 60%),
+          radial-gradient(1000px 900px at 60% 90%, rgba(0, 209, 255, 0.10), rgba(0,0,0,0) 60%),
+          #000;
         color: #e5e7eb;
         overflow: hidden;
       }
-      clawdis-a2ui-host { display: block; height: 100%; }
+      body::before {
+        content:"";
+        position: fixed;
+        inset: -20%;
+        background:
+          repeating-linear-gradient(0deg, rgba(255,255,255,0.03) 0, rgba(255,255,255,0.03) 1px,
+                                 transparent 1px, transparent 48px),
+          repeating-linear-gradient(90deg, rgba(255,255,255,0.03) 0, rgba(255,255,255,0.03) 1px,
+                                 transparent 1px, transparent 48px);
+        transform: translate3d(0,0,0) rotate(-7deg);
+        will-change: transform, opacity;
+        -webkit-backface-visibility: hidden;
+        backface-visibility: hidden;
+        opacity: 0.45;
+        pointer-events: none;
+        animation: clawdis-grid-drift 140s ease-in-out infinite alternate;
+      }
+      body::after {
+        content:"";
+        position: fixed;
+        inset: -35%;
+        background:
+          radial-gradient(900px 700px at 30% 30%, rgba(42,113,255,0.16), rgba(0,0,0,0) 60%),
+          radial-gradient(800px 650px at 70% 35%, rgba(255,0,138,0.12), rgba(0,0,0,0) 62%),
+          radial-gradient(900px 800px at 55% 75%, rgba(0,209,255,0.10), rgba(0,0,0,0) 62%);
+        filter: blur(28px);
+        opacity: 0.52;
+        will-change: transform, opacity;
+        -webkit-backface-visibility: hidden;
+        backface-visibility: hidden;
+        transform: translate3d(0,0,0);
+        pointer-events: none;
+        animation: clawdis-glow-drift 110s ease-in-out infinite alternate;
+      }
+      @supports (mix-blend-mode: screen) {
+        body::after { mix-blend-mode: screen; }
+      }
+      @supports not (mix-blend-mode: screen) {
+        body::after { opacity: 0.70; }
+      }
+      @keyframes clawdis-grid-drift {
+        0%   { transform: translate3d(-12px, 8px, 0) rotate(-7deg); opacity: 0.40; }
+        50%  { transform: translate3d( 10px,-7px, 0) rotate(-6.6deg); opacity: 0.56; }
+        100% { transform: translate3d(-8px,  6px, 0) rotate(-7.2deg); opacity: 0.42; }
+      }
+      @keyframes clawdis-glow-drift {
+        0%   { transform: translate3d(-18px, 12px, 0) scale(1.02); opacity: 0.40; }
+        50%  { transform: translate3d( 14px,-10px, 0) scale(1.05); opacity: 0.52; }
+        100% { transform: translate3d(-10px,  8px, 0) scale(1.03); opacity: 0.43; }
+      }
+      canvas {
+        position: fixed;
+        inset: 0;
+        display: block;
+        width: 100vw;
+        height: 100vh;
+        touch-action: none;
+        z-index: 1;
+      }
+      #clawdis-status {
+        position: fixed;
+        inset: 0;
+        display: grid;
+        place-items: center;
+        pointer-events: none;
+        z-index: 3;
+      }
+      #clawdis-status .card {
+        text-align: center;
+        padding: 16px 18px;
+        border-radius: 14px;
+        background: rgba(18, 18, 22, 0.42);
+        border: 1px solid rgba(255,255,255,0.08);
+        box-shadow: 0 18px 60px rgba(0,0,0,0.55);
+        -webkit-backdrop-filter: blur(14px);
+        backdrop-filter: blur(14px);
+      }
+      #clawdis-status .title {
+        font: 600 20px -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text", system-ui, sans-serif;
+        letter-spacing: 0.2px;
+        color: rgba(255,255,255,0.92);
+        text-shadow: 0 0 22px rgba(42, 113, 255, 0.35);
+      }
+      #clawdis-status .subtitle {
+        margin-top: 6px;
+        font: 500 12px -apple-system, BlinkMacSystemFont, "SF Pro Text", system-ui, sans-serif;
+        color: rgba(255,255,255,0.58);
+      }
+      clawdis-a2ui-host {
+        display: block;
+        height: 100%;
+        position: fixed;
+        inset: 0;
+        z-index: 4;
+        --clawdis-a2ui-inset-top: 28px;
+        --clawdis-a2ui-inset-right: 0px;
+        --clawdis-a2ui-inset-bottom: 0px;
+        --clawdis-a2ui-inset-left: 0px;
+        --clawdis-a2ui-scroll-pad-bottom: 0px;
+      }
     </style>
   </head>
   <body>
+    <canvas id="clawdis-canvas"></canvas>
+    <div id="clawdis-status">
+      <div class="card">
+        <div class="title" id="clawdis-status-title">Ready</div>
+        <div class="subtitle" id="clawdis-status-subtitle">Waiting for agent</div>
+      </div>
+    </div>
     <clawdis-a2ui-host></clawdis-a2ui-host>
     <script src="a2ui.bundle.js"></script>
+    <script>
+      (() => {
+        const canvas = document.getElementById('clawdis-canvas');
+        const ctx = canvas.getContext('2d');
+        const statusEl = document.getElementById('clawdis-status');
+        const titleEl = document.getElementById('clawdis-status-title');
+        const subtitleEl = document.getElementById('clawdis-status-subtitle');
+
+        function resize() {
+          const dpr = window.devicePixelRatio || 1;
+          const w = Math.max(1, Math.floor(window.innerWidth * dpr));
+          const h = Math.max(1, Math.floor(window.innerHeight * dpr));
+          canvas.width = w;
+          canvas.height = h;
+          ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        }
+
+        window.addEventListener('resize', resize);
+        resize();
+
+        window.__clawdis = {
+          canvas,
+          ctx,
+          setStatus: (title, subtitle) => {
+            if (!statusEl) return;
+            if (!title && !subtitle) {
+              statusEl.style.display = 'none';
+              return;
+            }
+            statusEl.style.display = 'grid';
+            if (titleEl && typeof title === 'string') titleEl.textContent = title;
+            if (subtitleEl && typeof subtitle === 'string') subtitleEl.textContent = subtitle;
+            clearTimeout(window.__statusTimeout);
+            window.__statusTimeout = setTimeout(() => {
+              statusEl.style.display = 'none';
+            }, 3000);
+          }
+        };
+      })();
+    </script>
   </body>
 </html>

src/cli/gateway-cli.ts

@@ -17,6 +17,8 @@ import { forceFreePortAndWait } from "./ports.js";
 type GatewayRpcOpts = {
   url?: string;
   token?: string;
+  username?: string;
+  password?: string;
   timeout?: string;
   expectFinal?: boolean;
 };
@@ -25,6 +27,8 @@ const gatewayCallOpts = (cmd: Command) =>
   cmd
     .option("--url <url>", "Gateway WebSocket URL", "ws://127.0.0.1:18789")
     .option("--token <token>", "Gateway token (if required)")
+    .option("--username <username>", "Gateway username (system auth)")
+    .option("--password <password>", "Gateway password (password/system auth)")
     .option("--timeout <ms>", "Timeout in ms", "10000")
     .option("--expect-final", "Wait for final response (agent)", false);
 
@@ -36,6 +40,8 @@ const callGatewayCli = async (
   callGateway({
     url: opts.url,
     token: opts.token,
+    username: opts.username,
+    password: opts.password,
     method,
     params,
     expectFinal: Boolean(opts.expectFinal),
@@ -57,6 +63,18 @@ export function registerGatewayCli(program: Command) {
       "--token <token>",
       "Shared token required in connect.params.auth.token (default: CLAWDIS_GATEWAY_TOKEN env if set)",
     )
+    .option("--auth <mode>", 'Gateway auth mode ("token"|"password"|"system")')
+    .option("--password <password>", "Password for auth mode=password")
+    .option("--username <username>", "Default username for system auth")
+    .option(
+      "--tailscale <mode>",
+      'Tailscale exposure mode ("off"|"serve"|"funnel")',
+    )
+    .option(
+      "--tailscale-reset-on-exit",
+      "Reset Tailscale serve/funnel configuration on shutdown",
+      false,
+    )
     .option("--verbose", "Verbose logging to stdout/stderr", false)
     .option(
       "--ws-log <style>",
@@ -97,6 +115,34 @@ export function registerGatewayCli(program: Command) {
       if (opts.token) {
         process.env.CLAWDIS_GATEWAY_TOKEN = String(opts.token);
       }
+      const authModeRaw = opts.auth ? String(opts.auth) : undefined;
+      const authMode =
+        authModeRaw === "token" ||
+        authModeRaw === "password" ||
+        authModeRaw === "system"
+          ? authModeRaw
+          : null;
+      if (authModeRaw && !authMode) {
+        defaultRuntime.error(
+          'Invalid --auth (use "token", "password", or "system")',
+        );
+        defaultRuntime.exit(1);
+        return;
+      }
+      const tailscaleRaw = opts.tailscale ? String(opts.tailscale) : undefined;
+      const tailscaleMode =
+        tailscaleRaw === "off" ||
+        tailscaleRaw === "serve" ||
+        tailscaleRaw === "funnel"
+          ? tailscaleRaw
+          : null;
+      if (tailscaleRaw && !tailscaleMode) {
+        defaultRuntime.error(
+          'Invalid --tailscale (use "off", "serve", or "funnel")',
+        );
+        defaultRuntime.exit(1);
+        return;
+      }
       const cfg = loadConfig();
       const bindRaw = String(opts.bind ?? cfg.gateway?.bind ?? "loopback");
       const bind =
@@ -157,7 +203,24 @@ export function registerGatewayCli(program: Command) {
       process.once("SIGINT", onSigint);
 
       try {
-        server = await startGatewayServer(port, { bind });
+        server = await startGatewayServer(port, {
+          bind,
+          auth:
+            authMode || opts.password || opts.username || authModeRaw
+              ? {
+                  mode: authMode ?? undefined,
+                  password: opts.password ? String(opts.password) : undefined,
+                  username: opts.username ? String(opts.username) : undefined,
+                }
+              : undefined,
+          tailscale:
+            tailscaleMode || opts.tailscaleResetOnExit
+              ? {
+                  mode: tailscaleMode ?? undefined,
+                  resetOnExit: Boolean(opts.tailscaleResetOnExit),
+                }
+              : undefined,
+        });
       } catch (err) {
         if (err instanceof GatewayLockError) {
           defaultRuntime.error(`Gateway failed to start: ${err.message}`);
@@ -183,6 +246,18 @@ export function registerGatewayCli(program: Command) {
       "--token <token>",
       "Shared token required in connect.params.auth.token (default: CLAWDIS_GATEWAY_TOKEN env if set)",
     )
+    .option("--auth <mode>", 'Gateway auth mode ("token"|"password"|"system")')
+    .option("--password <password>", "Password for auth mode=password")
+    .option("--username <username>", "Default username for system auth")
+    .option(
+      "--tailscale <mode>",
+      'Tailscale exposure mode ("off"|"serve"|"funnel")',
+    )
+    .option(
+      "--tailscale-reset-on-exit",
+      "Reset Tailscale serve/funnel configuration on shutdown",
+      false,
+    )
     .option(
       "--allow-unconfigured",
       "Allow gateway start without gateway.mode=local in config",
@@ -267,6 +342,34 @@ export function registerGatewayCli(program: Command) {
       if (opts.token) {
         process.env.CLAWDIS_GATEWAY_TOKEN = String(opts.token);
       }
+      const authModeRaw = opts.auth ? String(opts.auth) : undefined;
+      const authMode =
+        authModeRaw === "token" ||
+        authModeRaw === "password" ||
+        authModeRaw === "system"
+          ? authModeRaw
+          : null;
+      if (authModeRaw && !authMode) {
+        defaultRuntime.error(
+          'Invalid --auth (use "token", "password", or "system")',
+        );
+        defaultRuntime.exit(1);
+        return;
+      }
+      const tailscaleRaw = opts.tailscale ? String(opts.tailscale) : undefined;
+      const tailscaleMode =
+        tailscaleRaw === "off" ||
+        tailscaleRaw === "serve" ||
+        tailscaleRaw === "funnel"
+          ? tailscaleRaw
+          : null;
+      if (tailscaleRaw && !tailscaleMode) {
+        defaultRuntime.error(
+          'Invalid --tailscale (use "off", "serve", or "funnel")',
+        );
+        defaultRuntime.exit(1);
+        return;
+      }
       const cfg = loadConfig();
       const configExists = fs.existsSync(CONFIG_PATH_CLAWDIS);
       const mode = cfg.gateway?.mode;
@@ -344,7 +447,24 @@ export function registerGatewayCli(program: Command) {
       process.once("SIGINT", onSigint);
 
       try {
-        server = await startGatewayServer(port, { bind });
+        server = await startGatewayServer(port, {
+          bind,
+          auth:
+            authMode || opts.password || opts.username || authModeRaw
+              ? {
+                  mode: authMode ?? undefined,
+                  password: opts.password ? String(opts.password) : undefined,
+                  username: opts.username ? String(opts.username) : undefined,
+                }
+              : undefined,
+          tailscale:
+            tailscaleMode || opts.tailscaleResetOnExit
+              ? {
+                  mode: tailscaleMode ?? undefined,
+                  resetOnExit: Boolean(opts.tailscaleResetOnExit),
+                }
+              : undefined,
+        });
       } catch (err) {
         if (err instanceof GatewayLockError) {
           defaultRuntime.error(`Gateway failed to start: ${err.message}`);

src/commands/health.ts

@@ -3,7 +3,7 @@ import { loadSessionStore, resolveStorePath } from "../config/sessions.js";
 import { callGateway } from "../gateway/call.js";
 import { info } from "../globals.js";
 import type { RuntimeEnv } from "../runtime.js";
-import { makeProxyFetch } from "../telegram/proxy.js";
+import { probeTelegram, type TelegramProbe } from "../telegram/probe.js";
 import { resolveHeartbeatSeconds } from "../web/reconnect.js";
 import {
   getWebAuthAgeMs,
@@ -11,15 +11,6 @@ import {
   webAuthExists,
 } from "../web/session.js";
 
-type TelegramProbe = {
-  ok: boolean;
-  status?: number | null;
-  error?: string | null;
-  elapsedMs: number;
-  bot?: { id?: number | null; username?: string | null };
-  webhook?: { url?: string | null; hasCustomCert?: boolean | null };
-};
-
 export type HealthSummary = {
   /**
    * Convenience top-level flag for UIs (e.g. WebChat) that only need a binary
@@ -56,94 +47,6 @@ export type HealthSummary = {
 };
 
 const DEFAULT_TIMEOUT_MS = 10_000;
-const TELEGRAM_API_BASE = "https://api.telegram.org";
-
-async function fetchWithTimeout(
-  url: string,
-  timeoutMs: number,
-  fetcher: typeof fetch,
-): Promise<Response> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await fetcher(url, { signal: controller.signal });
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-async function probeTelegram(
-  token: string,
-  timeoutMs: number,
-  proxyUrl?: string,
-): Promise<TelegramProbe> {
-  const started = Date.now();
-  const fetcher = proxyUrl ? makeProxyFetch(proxyUrl) : fetch;
-  const base = `${TELEGRAM_API_BASE}/bot${token}`;
-
-  const result: TelegramProbe = {
-    ok: false,
-    status: null,
-    error: null,
-    elapsedMs: 0,
-  };
-
-  try {
-    const meRes = await fetchWithTimeout(`${base}/getMe`, timeoutMs, fetcher);
-    const meJson = (await meRes.json()) as {
-      ok?: boolean;
-      description?: string;
-      result?: { id?: number; username?: string };
-    };
-    if (!meRes.ok || !meJson?.ok) {
-      result.status = meRes.status;
-      result.error = meJson?.description ?? `getMe failed (${meRes.status})`;
-      return { ...result, elapsedMs: Date.now() - started };
-    }
-
-    result.bot = {
-      id: meJson.result?.id ?? null,
-      username: meJson.result?.username ?? null,
-    };
-
-    // Try to fetch webhook info, but don't fail health if it errors
-    try {
-      const webhookRes = await fetchWithTimeout(
-        `${base}/getWebhookInfo`,
-        timeoutMs,
-        fetcher,
-      );
-      const webhookJson = (await webhookRes.json()) as {
-        ok?: boolean;
-        result?: {
-          url?: string;
-          has_custom_certificate?: boolean;
-        };
-      };
-      if (webhookRes.ok && webhookJson?.ok) {
-        result.webhook = {
-          url: webhookJson.result?.url ?? null,
-          hasCustomCert: webhookJson.result?.has_custom_certificate ?? null,
-        };
-      }
-    } catch {
-      // ignore webhook errors for health
-    }
-
-    result.ok = true;
-    result.status = null;
-    result.error = null;
-    result.elapsedMs = Date.now() - started;
-    return result;
-  } catch (err) {
-    return {
-      ...result,
-      status: err instanceof Response ? err.status : result.status,
-      error: err instanceof Error ? err.message : String(err),
-      elapsedMs: Date.now() - started,
-    };
-  }
-}
 
 export async function getHealthSnapshot(
   timeoutMs?: number,

src/config/config.ts

@@ -106,6 +106,28 @@ export type GatewayControlUiConfig = {
   enabled?: boolean;
 };
 
+export type GatewayAuthMode = "token" | "password" | "system";
+
+export type GatewayAuthConfig = {
+  /** Authentication mode for Gateway connections. Defaults to token when set. */
+  mode?: GatewayAuthMode;
+  /** Username for system auth (PAM). Defaults to current user. */
+  username?: string;
+  /** Shared password for password mode (consider env instead). */
+  password?: string;
+  /** Allow Tailscale identity headers when serve mode is enabled. */
+  allowTailscale?: boolean;
+};
+
+export type GatewayTailscaleMode = "off" | "serve" | "funnel";
+
+export type GatewayTailscaleConfig = {
+  /** Tailscale exposure mode for the Gateway control UI. */
+  mode?: GatewayTailscaleMode;
+  /** Reset serve/funnel configuration on shutdown. */
+  resetOnExit?: boolean;
+};
+
 export type GatewayConfig = {
   /**
    * Explicit gateway mode. When set to "remote", local gateway start is disabled.
@@ -118,6 +140,8 @@ export type GatewayConfig = {
    */
   bind?: BridgeBindMode;
   controlUi?: GatewayControlUiConfig;
+  auth?: GatewayAuthConfig;
+  tailscale?: GatewayTailscaleConfig;
 };
 
 export type SkillConfig = {
@@ -370,6 +394,28 @@ const ClawdisSchema = z.object({
           enabled: z.boolean().optional(),
         })
         .optional(),
+      auth: z
+        .object({
+          mode: z
+            .union([
+              z.literal("token"),
+              z.literal("password"),
+              z.literal("system"),
+            ])
+            .optional(),
+          username: z.string().optional(),
+          password: z.string().optional(),
+          allowTailscale: z.boolean().optional(),
+        })
+        .optional(),
+      tailscale: z
+        .object({
+          mode: z
+            .union([z.literal("off"), z.literal("serve"), z.literal("funnel")])
+            .optional(),
+          resetOnExit: z.boolean().optional(),
+        })
+        .optional(),
     })
     .optional(),
   skillsLoad: z

src/gateway/auth.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, it } from "vitest";
+
+import { authorizeGatewayConnect } from "./auth.js";
+
+describe("gateway auth", () => {
+  it("does not throw when req is missing socket", async () => {
+    const res = await authorizeGatewayConnect({
+      auth: { mode: "none", allowTailscale: false },
+      connectAuth: null,
+      // Regression: avoid crashing on req.socket.remoteAddress when callers pass a non-IncomingMessage.
+      req: {} as never,
+    });
+    expect(res.ok).toBe(true);
+  });
+});

src/gateway/auth.ts

@@ -0,0 +1,200 @@
+import { timingSafeEqual } from "node:crypto";
+import type { IncomingMessage } from "node:http";
+import os from "node:os";
+
+import { type PamAvailability, verifyPamCredentials } from "../infra/pam.js";
+
+export type ResolvedGatewayAuthMode = "none" | "token" | "password" | "system";
+
+export type ResolvedGatewayAuth = {
+  mode: ResolvedGatewayAuthMode;
+  token?: string;
+  password?: string;
+  username?: string;
+  allowTailscale: boolean;
+};
+
+export type GatewayAuthResult = {
+  ok: boolean;
+  method?: "none" | "token" | "password" | "system" | "tailscale";
+  user?: string;
+  reason?: string;
+};
+
+type ConnectAuth = {
+  token?: string;
+  username?: string;
+  password?: string;
+};
+
+type TailscaleUser = {
+  login: string;
+  name: string;
+  profilePic?: string;
+};
+
+function safeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(Buffer.from(a), Buffer.from(b));
+}
+
+function isLoopbackAddress(ip: string | undefined): boolean {
+  if (!ip) return false;
+  if (ip === "127.0.0.1") return true;
+  if (ip.startsWith("127.")) return true;
+  if (ip === "::1") return true;
+  if (ip.startsWith("::ffff:127.")) return true;
+  return false;
+}
+
+function isLocalDirectRequest(req?: IncomingMessage): boolean {
+  if (!req) return false;
+  const clientIp = req.socket?.remoteAddress ?? "";
+  if (!isLoopbackAddress(clientIp)) return false;
+
+  const host = (req.headers.host ?? "").toLowerCase();
+  const hostIsLocal =
+    host.startsWith("localhost") ||
+    host.startsWith("127.0.0.1") ||
+    host.startsWith("[::1]");
+
+  const hasForwarded = Boolean(
+    req.headers["x-forwarded-for"] ||
+      req.headers["x-real-ip"] ||
+      req.headers["x-forwarded-host"],
+  );
+
+  return hostIsLocal && !hasForwarded;
+}
+
+function getTailscaleUser(req?: IncomingMessage): TailscaleUser | null {
+  if (!req) return null;
+  const login = req.headers["tailscale-user-login"];
+  if (typeof login !== "string" || !login.trim()) return null;
+  const nameRaw = req.headers["tailscale-user-name"];
+  const profilePic = req.headers["tailscale-user-profile-pic"];
+  const name =
+    typeof nameRaw === "string" && nameRaw.trim()
+      ? nameRaw.trim()
+      : login.trim();
+  return {
+    login: login.trim(),
+    name,
+    profilePic:
+      typeof profilePic === "string" && profilePic.trim()
+        ? profilePic.trim()
+        : undefined,
+  };
+}
+
+function hasTailscaleProxyHeaders(req?: IncomingMessage): boolean {
+  if (!req) return false;
+  return Boolean(
+    req.headers["x-forwarded-for"] &&
+      req.headers["x-forwarded-proto"] &&
+      req.headers["x-forwarded-host"],
+  );
+}
+
+function isTailscaleProxyRequest(req?: IncomingMessage): boolean {
+  if (!req) return false;
+  return (
+    isLoopbackAddress(req.socket?.remoteAddress) &&
+    hasTailscaleProxyHeaders(req)
+  );
+}
+
+export function assertGatewayAuthConfigured(
+  auth: ResolvedGatewayAuth,
+  pam: PamAvailability,
+): void {
+  if (auth.mode === "token" && !auth.token) {
+    throw new Error(
+      "gateway auth mode is token, but CLAWDIS_GATEWAY_TOKEN is not set",
+    );
+  }
+  if (auth.mode === "password" && !auth.password) {
+    throw new Error(
+      "gateway auth mode is password, but no password was configured",
+    );
+  }
+  if (auth.mode === "system" && !pam.available) {
+    throw new Error(
+      `gateway auth mode is system, but PAM auth is unavailable${
+        pam.error ? `: ${pam.error}` : ""
+      }`,
+    );
+  }
+}
+
+export async function authorizeGatewayConnect(params: {
+  auth: ResolvedGatewayAuth;
+  connectAuth?: ConnectAuth | null;
+  req?: IncomingMessage;
+}): Promise<GatewayAuthResult> {
+  const { auth, connectAuth, req } = params;
+  const localDirect = isLocalDirectRequest(req);
+
+  if (auth.mode === "none") {
+    if (auth.allowTailscale && !localDirect) {
+      const tailscaleUser = getTailscaleUser(req);
+      if (!tailscaleUser) {
+        return { ok: false, reason: "unauthorized" };
+      }
+      if (!isTailscaleProxyRequest(req)) {
+        return { ok: false, reason: "unauthorized" };
+      }
+      return {
+        ok: true,
+        method: "tailscale",
+        user: tailscaleUser.login,
+      };
+    }
+    return { ok: true, method: "none" };
+  }
+
+  if (auth.mode === "token") {
+    if (auth.token && connectAuth?.token === auth.token) {
+      return { ok: true, method: "token" };
+    }
+  }
+
+  if (auth.mode === "password") {
+    const password = connectAuth?.password;
+    if (!password || !auth.password) {
+      return { ok: false, reason: "unauthorized" };
+    }
+    if (!safeEqual(password, auth.password)) {
+      return { ok: false, reason: "unauthorized" };
+    }
+    return { ok: true, method: "password" };
+  }
+
+  if (auth.mode === "system") {
+    const password = connectAuth?.password;
+    if (!password) return { ok: false, reason: "unauthorized" };
+    const username = (
+      connectAuth?.username ??
+      auth.username ??
+      os.userInfo().username
+    ).trim();
+    if (!username) return { ok: false, reason: "unauthorized" };
+    const ok = await verifyPamCredentials(username, password);
+    return ok
+      ? { ok: true, method: "system", user: username }
+      : { ok: false, reason: "unauthorized" };
+  }
+
+  if (auth.allowTailscale) {
+    const tailscaleUser = getTailscaleUser(req);
+    if (tailscaleUser && isTailscaleProxyRequest(req)) {
+      return {
+        ok: true,
+        method: "tailscale",
+        user: tailscaleUser.login,
+      };
+    }
+  }
+
+  return { ok: false, reason: "unauthorized" };
+}

src/gateway/call.ts

@@ -5,6 +5,8 @@ import { PROTOCOL_VERSION } from "./protocol/index.js";
 export type CallGatewayOptions = {
   url?: string;
   token?: string;
+  username?: string;
+  password?: string;
   method: string;
   params?: unknown;
   expectFinal?: boolean;
@@ -35,6 +37,8 @@ export async function callGateway<T = unknown>(
     const client = new GatewayClient({
       url: opts.url,
       token: opts.token,
+      username: opts.username,
+      password: opts.password,
       instanceId: opts.instanceId ?? randomUUID(),
       clientName: opts.clientName ?? "cli",
       clientVersion: opts.clientVersion ?? "dev",

src/gateway/client.ts

@@ -19,6 +19,8 @@ type Pending = {
 export type GatewayClientOptions = {
   url?: string; // ws://127.0.0.1:18789
   token?: string;
+  username?: string;
+  password?: string;
   instanceId?: string;
   clientName?: string;
   clientVersion?: string;
@@ -81,6 +83,14 @@ export class GatewayClient {
   }
 
   private sendConnect() {
+    const auth =
+      this.opts.token || this.opts.password || this.opts.username
+        ? {
+            token: this.opts.token,
+            username: this.opts.username,
+            password: this.opts.password,
+          }
+        : undefined;
     const params: ConnectParams = {
       minProtocol: this.opts.minProtocol ?? PROTOCOL_VERSION,
       maxProtocol: this.opts.maxProtocol ?? PROTOCOL_VERSION,
@@ -92,7 +102,7 @@ export class GatewayClient {
         instanceId: this.opts.instanceId,
       },
       caps: [],
-      auth: this.opts.token ? { token: this.opts.token } : undefined,
+      auth,
     };
 
     void this.request<HelloOk>("connect", params)

src/gateway/protocol/schema.ts

@@ -77,6 +77,8 @@ export const ConnectParamsSchema = Type.Object(
       Type.Object(
         {
           token: Type.Optional(Type.String()),
+          username: Type.Optional(Type.String()),
+          password: Type.Optional(Type.String()),
         },
         { additionalProperties: false },
       ),

src/gateway/server.test.ts

@@ -6,6 +6,7 @@ import path from "node:path";
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { WebSocket } from "ws";
 import { agentCommand } from "../commands/agent.js";
+import { readConfigFileSnapshot, writeConfigFile } from "../config/config.js";
 import { emitAgentEvent } from "../infra/agent-events.js";
 import { GatewayLockError } from "../infra/gateway-lock.js";
 import { emitHeartbeatEvent } from "../infra/heartbeat-events.js";
@@ -113,6 +114,7 @@ let testAllowFrom: string[] | undefined;
 let testCronStorePath: string | undefined;
 let testCronEnabled: boolean | undefined = false;
 let testGatewayBind: "auto" | "lan" | "tailnet" | "loopback" | undefined;
+let testGatewayAuth: Record<string, unknown> | undefined;
 const sessionStoreSaveDelayMs = vi.hoisted(() => ({ value: 0 }));
 vi.mock("../config/sessions.js", async () => {
   const actual = await vi.importActual<typeof import("../config/sessions.js")>(
@@ -129,23 +131,97 @@ vi.mock("../config/sessions.js", async () => {
     }),
   };
 });
-vi.mock("../config/config.js", () => ({
-  loadConfig: () => ({
-    inbound: {
-      allowFrom: testAllowFrom,
-      workspace: path.join(os.tmpdir(), "clawd-gateway-test"),
-      agent: { provider: "anthropic", model: "claude-opus-4-5" },
-      session: { mainKey: "main", store: testSessionStorePath },
+vi.mock("../config/config.js", () => {
+  const resolveConfigPath = () =>
+    path.join(os.homedir(), ".clawdis", "clawdis.json");
+
+  const readConfigFileSnapshot = async () => {
+    const configPath = resolveConfigPath();
+    try {
+      await fs.access(configPath);
+    } catch {
+      return {
+        path: configPath,
+        exists: false,
+        raw: null,
+        parsed: {},
+        valid: true,
+        config: {},
+        issues: [],
+      };
+    }
+    try {
+      const raw = await fs.readFile(configPath, "utf-8");
+      const parsed = JSON.parse(raw) as Record<string, unknown>;
+      return {
+        path: configPath,
+        exists: true,
+        raw,
+        parsed,
+        valid: true,
+        config: parsed,
+        issues: [],
+      };
+    } catch (err) {
+      return {
+        path: configPath,
+        exists: true,
+        raw: null,
+        parsed: {},
+        valid: false,
+        config: {},
+        issues: [{ path: "", message: `read failed: ${String(err)}` }],
+      };
+    }
+  };
+
+  const writeConfigFile = async (cfg: Record<string, unknown>) => {
+    const configPath = resolveConfigPath();
+    await fs.mkdir(path.dirname(configPath), { recursive: true });
+    const raw = JSON.stringify(cfg, null, 2).trimEnd().concat("\n");
+    await fs.writeFile(configPath, raw, "utf-8");
+  };
+
+  return {
+    CONFIG_PATH_CLAWDIS: resolveConfigPath(),
+    loadConfig: () => ({
+      inbound: {
+        allowFrom: testAllowFrom,
+        workspace: path.join(os.tmpdir(), "clawd-gateway-test"),
+        agent: { provider: "anthropic", model: "claude-opus-4-5" },
+        session: { mainKey: "main", store: testSessionStorePath },
+      },
+      gateway: (() => {
+        const gateway: Record<string, unknown> = {};
+        if (testGatewayBind) gateway.bind = testGatewayBind;
+        if (testGatewayAuth) gateway.auth = testGatewayAuth;
+        return Object.keys(gateway).length > 0 ? gateway : undefined;
+      })(),
+      cron: (() => {
+        const cron: Record<string, unknown> = {};
+        if (typeof testCronEnabled === "boolean")
+          cron.enabled = testCronEnabled;
+        if (typeof testCronStorePath === "string")
+          cron.store = testCronStorePath;
+        return Object.keys(cron).length > 0 ? cron : undefined;
+      })(),
+    }),
+    parseConfigJson5: (raw: string) => {
+      try {
+        return { ok: true, parsed: JSON.parse(raw) as unknown };
+      } catch (err) {
+        return { ok: false, error: String(err) };
+      }
     },
-    gateway: testGatewayBind ? { bind: testGatewayBind } : undefined,
-    cron: (() => {
-      const cron: Record<string, unknown> = {};
-      if (typeof testCronEnabled === "boolean") cron.enabled = testCronEnabled;
-      if (typeof testCronStorePath === "string") cron.store = testCronStorePath;
-      return Object.keys(cron).length > 0 ? cron : undefined;
-    })(),
-  }),
-}));
+    validateConfigObject: (parsed: unknown) => ({
+      ok: true,
+      config: parsed as Record<string, unknown>,
+      issues: [],
+    }),
+    readConfigFileSnapshot,
+    writeConfigFile,
+  };
+});
 
 vi.mock("../commands/health.js", () => ({
   getHealthSnapshot: vi.fn().mockResolvedValue({ ok: true, stub: true }),
@@ -174,6 +250,7 @@ beforeEach(async () => {
   sessionStoreSaveDelayMs.value = 0;
   testTailnetIPv4.value = undefined;
   testGatewayBind = undefined;
+  testGatewayAuth = undefined;
   __resetModelCatalogCacheForTest();
   piAiMock.enabled = false;
   piAiMock.getModelsCalls.length = 0;
@@ -265,6 +342,8 @@ async function connectReq(
   ws: WebSocket,
   opts?: {
     token?: string;
+    username?: string;
+    password?: string;
     minProtocol?: number;
     maxProtocol?: number;
     client?: {
@@ -292,7 +371,14 @@ async function connectReq(
           mode: "test",
         },
         caps: [],
-        auth: opts?.token ? { token: opts.token } : undefined,
+        auth:
+          opts?.token || opts?.password || opts?.username
+            ? {
+                token: opts?.token,
+                username: opts?.username,
+                password: opts?.password,
+              }
+            : undefined,
       },
     }),
   );
@@ -1781,6 +1867,35 @@ describe("gateway server", () => {
     process.env.CLAWDIS_GATEWAY_TOKEN = prevToken;
   });
 
+  test("accepts password auth when configured", async () => {
+    testGatewayAuth = { mode: "password", password: "secret" };
+    const port = await getFreePort();
+    const server = await startGatewayServer(port);
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    await new Promise<void>((resolve) => ws.once("open", resolve));
+
+    const res = await connectReq(ws, { password: "secret" });
+    expect(res.ok).toBe(true);
+
+    ws.close();
+    await server.close();
+  });
+
+  test("rejects invalid password", async () => {
+    testGatewayAuth = { mode: "password", password: "secret" };
+    const port = await getFreePort();
+    const server = await startGatewayServer(port);
+    const ws = new WebSocket(`ws://127.0.0.1:${port}`);
+    await new Promise<void>((resolve) => ws.once("open", resolve));
+
+    const res = await connectReq(ws, { password: "wrong" });
+    expect(res.ok).toBe(false);
+    expect(res.error?.message ?? "").toContain("unauthorized");
+
+    ws.close();
+    await server.close();
+  });
+
   test(
     "closes silent handshakes after timeout",
     { timeout: 15_000 },
@@ -1890,6 +2005,81 @@ describe("gateway server", () => {
     },
   );
 
+  test("providers.status returns snapshot without probe", async () => {
+    const prevToken = process.env.TELEGRAM_BOT_TOKEN;
+    delete process.env.TELEGRAM_BOT_TOKEN;
+    const { server, ws } = await startServerWithClient();
+    await connectOk(ws);
+
+    const res = await rpcReq<{
+      whatsapp?: { linked?: boolean };
+      telegram?: {
+        configured?: boolean;
+        tokenSource?: string;
+        probe?: unknown;
+        lastProbeAt?: unknown;
+      };
+    }>(ws, "providers.status", { probe: false, timeoutMs: 2000 });
+    expect(res.ok).toBe(true);
+    expect(res.payload?.whatsapp).toBeTruthy();
+    expect(res.payload?.telegram?.configured).toBe(false);
+    expect(res.payload?.telegram?.tokenSource).toBe("none");
+    expect(res.payload?.telegram?.probe).toBeUndefined();
+    expect(res.payload?.telegram?.lastProbeAt).toBeNull();
+
+    ws.close();
+    await server.close();
+    if (prevToken === undefined) {
+      delete process.env.TELEGRAM_BOT_TOKEN;
+    } else {
+      process.env.TELEGRAM_BOT_TOKEN = prevToken;
+    }
+  });
+
+  test("web.logout reports no session when missing", async () => {
+    const { server, ws } = await startServerWithClient();
+    await connectOk(ws);
+
+    const res = await rpcReq<{ cleared?: boolean }>(ws, "web.logout");
+    expect(res.ok).toBe(true);
+    expect(res.payload?.cleared).toBe(false);
+
+    ws.close();
+    await server.close();
+  });
+
+  test("telegram.logout clears bot token from config", async () => {
+    const prevToken = process.env.TELEGRAM_BOT_TOKEN;
+    delete process.env.TELEGRAM_BOT_TOKEN;
+    await writeConfigFile({
+      telegram: { botToken: "123:abc", requireMention: false },
+    });
+
+    const { server, ws } = await startServerWithClient();
+    await connectOk(ws);
+
+    const res = await rpcReq<{ cleared?: boolean; envToken?: boolean }>(
+      ws,
+      "telegram.logout",
+    );
+    expect(res.ok).toBe(true);
+    expect(res.payload?.cleared).toBe(true);
+    expect(res.payload?.envToken).toBe(false);
+
+    const snap = await readConfigFileSnapshot();
+    expect(snap.valid).toBe(true);
+    expect(snap.config?.telegram?.botToken).toBeUndefined();
+    expect(snap.config?.telegram?.requireMention).toBe(false);
+
+    ws.close();
+    await server.close();
+    if (prevToken === undefined) {
+      delete process.env.TELEGRAM_BOT_TOKEN;
+    } else {
+      process.env.TELEGRAM_BOT_TOKEN = prevToken;
+    }
+  });
+
   test(
     "presence events carry seq + stateVersion",
     { timeout: 8000 },

src/gateway/server.ts

@@ -73,8 +73,12 @@ import {
   requestNodePairing,
   verifyNodeToken,
 } from "../infra/node-pairing.js";
+import { getPamAvailability } from "../infra/pam.js";
 import { ensureClawdisCliOnPath } from "../infra/path-env.js";
-import { enqueueSystemEvent } from "../infra/system-events.js";
+import {
+  enqueueSystemEvent,
+  isSystemEventContextChanged,
+} from "../infra/system-events.js";
 import {
   listSystemPresence,
   updateSystemPresence,
@@ -84,7 +88,13 @@ import {
   pickPrimaryTailnetIPv4,
   pickPrimaryTailnetIPv6,
 } from "../infra/tailnet.js";
-import { getTailnetHostname } from "../infra/tailscale.js";
+import {
+  disableTailscaleFunnel,
+  disableTailscaleServe,
+  enableTailscaleFunnel,
+  enableTailscaleServe,
+  getTailnetHostname,
+} from "../infra/tailscale.js";
 import {
   defaultVoiceWakeTriggers,
   loadVoiceWakeConfig,
@@ -112,6 +122,11 @@ import { startWebLoginWithQr, waitForWebLogin } from "../web/login-qr.js";
 import { sendMessageWhatsApp } from "../web/outbound.js";
 import { requestReplyHeartbeatNow } from "../web/reply-heartbeat-wake.js";
 import { getWebAuthAgeMs, logoutWeb, readWebSelfId } from "../web/session.js";
+import {
+  assertGatewayAuthConfigured,
+  authorizeGatewayConnect,
+  type ResolvedGatewayAuth,
+} from "./auth.js";
 import { buildMessageWithAttachments } from "./chat-attachments.js";
 import { handleControlUiHttpRequest } from "./control-ui.js";
 
@@ -417,6 +432,14 @@ export type GatewayServerOptions = {
    * Default: config `gateway.controlUi.enabled` (or true when absent).
    */
   controlUiEnabled?: boolean;
+  /**
+   * Override gateway auth configuration (merges with config).
+   */
+  auth?: import("../config/config.js").GatewayAuthConfig;
+  /**
+   * Override gateway Tailscale exposure configuration (merges with config).
+   */
+  tailscale?: import("../config/config.js").GatewayTailscaleConfig;
   /**
    * Test-only: allow canvas host startup even when NODE_ENV/VITEST would disable it.
    */
@@ -1094,12 +1117,52 @@ export async function startGatewayServer(
   }
   const controlUiEnabled =
     opts.controlUiEnabled ?? cfgAtStart.gateway?.controlUi?.enabled ?? true;
+  const authConfig = {
+    ...(cfgAtStart.gateway?.auth ?? {}),
+    ...(opts.auth ?? {}),
+  };
+  const tailscaleConfig = {
+    ...(cfgAtStart.gateway?.tailscale ?? {}),
+    ...(opts.tailscale ?? {}),
+  };
+  const tailscaleMode = tailscaleConfig.mode ?? "off";
+  const token = getGatewayToken();
+  const password =
+    authConfig.password ?? process.env.CLAWDIS_GATEWAY_PASSWORD ?? undefined;
+  const username =
+    authConfig.username ?? process.env.CLAWDIS_GATEWAY_USERNAME ?? undefined;
+  const authMode: ResolvedGatewayAuth["mode"] =
+    authConfig.mode ?? (password ? "password" : token ? "token" : "none");
+  const allowTailscale =
+    authConfig.allowTailscale ??
+    (tailscaleMode === "serve" &&
+      authMode !== "password" &&
+      authMode !== "system");
+  const resolvedAuth: ResolvedGatewayAuth = {
+    mode: authMode,
+    token,
+    password,
+    username,
+    allowTailscale,
+  };
   const canvasHostEnabled =
     process.env.CLAWDIS_SKIP_CANVAS_HOST !== "1" &&
     cfgAtStart.canvasHost?.enabled !== false;
-  if (!isLoopbackHost(bindHost) && !getGatewayToken()) {
+  const pamAvailability = await getPamAvailability();
+  assertGatewayAuthConfigured(resolvedAuth, pamAvailability);
+  if (tailscaleMode === "funnel" && authMode === "none") {
     throw new Error(
-      `refusing to bind gateway to ${bindHost}:${port} without CLAWDIS_GATEWAY_TOKEN`,
+      "tailscale funnel requires gateway auth (set gateway.auth or CLAWDIS_GATEWAY_TOKEN)",
+    );
+  }
+  if (tailscaleMode !== "off" && !isLoopbackHost(bindHost)) {
+    throw new Error(
+      "tailscale serve/funnel requires gateway bind=loopback (127.0.0.1)",
+    );
+  }
+  if (!isLoopbackHost(bindHost) && authMode === "none") {
+    throw new Error(
+      `refusing to bind gateway to ${bindHost}:${port} without auth (set gateway.auth or CLAWDIS_GATEWAY_TOKEN)`,
     );
   }
 
@@ -2615,7 +2678,7 @@ export async function startGatewayServer(
     .start()
     .catch((err) => logError(`cron failed to start: ${String(err)}`));
 
-  wss.on("connection", (socket, req) => {
+  wss.on("connection", (socket, upgradeReq) => {
     let client: Client | null = null;
     let closed = false;
     const connId = randomUUID();
@@ -2629,7 +2692,7 @@ export async function startGatewayServer(
         ? bridgeHost
         : undefined;
     const canvasHostUrl = deriveCanvasHostUrl(
-      req,
+      upgradeReq,
       canvasHostPortForWs,
       canvasHostServer ? canvasHostOverride : undefined,
     );
@@ -2743,8 +2806,8 @@ export async function startGatewayServer(
             return;
           }
 
-          const req = parsed as RequestFrame;
-          const connectParams = req.params as ConnectParams;
+          const frame = parsed as RequestFrame;
+          const connectParams = frame.params as ConnectParams;
 
           // protocol negotiation
           const { minProtocol, maxProtocol } = connectParams;
@@ -2757,7 +2820,7 @@ export async function startGatewayServer(
             );
             send({
               type: "res",
-              id: req.id,
+              id: frame.id,
               ok: false,
               error: errorShape(
                 ErrorCodes.INVALID_REQUEST,
@@ -2772,15 +2835,18 @@ export async function startGatewayServer(
             return;
           }
 
-          // token auth if required
-          const token = getGatewayToken();
-          if (token && connectParams.auth?.token !== token) {
+          const authResult = await authorizeGatewayConnect({
+            auth: resolvedAuth,
+            connectAuth: connectParams.auth,
+            req: upgradeReq,
+          });
+          if (!authResult.ok) {
             logWarn(
               `[gws] unauthorized conn=${connId} remote=${remoteAddr ?? "?"} client=${connectParams.client.name} ${connectParams.client.mode} v${connectParams.client.version}`,
             );
             send({
               type: "res",
-              id: req.id,
+              id: frame.id,
               ok: false,
               error: errorShape(ErrorCodes.INVALID_REQUEST, "unauthorized"),
             });
@@ -2788,6 +2854,7 @@ export async function startGatewayServer(
             close();
             return;
           }
+          const authMethod = authResult.method ?? "none";
 
           const shouldTrackPresence = connectParams.client.mode !== "cli";
           const presenceKey = shouldTrackPresence
@@ -2801,7 +2868,7 @@ export async function startGatewayServer(
             mode: connectParams.client.mode,
             instanceId: connectParams.client.instanceId,
             platform: connectParams.client.platform,
-            token: connectParams.auth?.token ? "set" : "none",
+            auth: authMethod,
           });
 
           if (isWebchatConnect(connectParams)) {
@@ -2863,7 +2930,7 @@ export async function startGatewayServer(
             stateVersion: snapshot.stateVersion.presence,
           });
 
-          send({ type: "res", id: req.id, ok: true, payload: helloOk });
+          send({ type: "res", id: frame.id, ok: true, payload: helloOk });
 
           clients.add(client);
           void refreshHealthSnapshot({ probe: true }).catch((err) =>
@@ -4014,7 +4081,7 @@ export async function startGatewayServer(
                 params.tags.every((t) => typeof t === "string")
                   ? (params.tags as string[])
                   : undefined;
-              updateSystemPresence({
+              const presenceUpdate = updateSystemPresence({
                 text,
                 instanceId,
                 host,
@@ -4029,17 +4096,55 @@ export async function startGatewayServer(
                 tags,
               });
               const isNodePresenceLine = text.startsWith("Node:");
-              const normalizedReason = (reason ?? "").toLowerCase();
-              const looksPeriodic =
-                normalizedReason.startsWith("periodic") ||
-                normalizedReason === "heartbeat";
-              if (!(isNodePresenceLine && looksPeriodic)) {
-                const compactNodeText =
-                  isNodePresenceLine &&
-                  (host || ip || version || mode || reason)
-                    ? `Node: ${host?.trim() || "Unknown"}${ip ? ` (${ip})` : ""} · app ${version?.trim() || "unknown"} · mode ${mode?.trim() || "unknown"} · reason ${reason?.trim() || "event"}`
-                    : text;
-                enqueueSystemEvent(compactNodeText);
+              if (isNodePresenceLine) {
+                const next = presenceUpdate.next;
+                const changed = new Set(presenceUpdate.changedKeys);
+                const reasonValue = next.reason ?? reason;
+                const normalizedReason = (reasonValue ?? "").toLowerCase();
+                const ignoreReason =
+                  normalizedReason.startsWith("periodic") ||
+                  normalizedReason === "heartbeat";
+                const hostChanged = changed.has("host");
+                const ipChanged = changed.has("ip");
+                const versionChanged = changed.has("version");
+                const modeChanged = changed.has("mode");
+                const reasonChanged = changed.has("reason") && !ignoreReason;
+                const hasChanges =
+                  hostChanged ||
+                  ipChanged ||
+                  versionChanged ||
+                  modeChanged ||
+                  reasonChanged;
+                if (hasChanges) {
+                  const contextChanged = isSystemEventContextChanged(
+                    presenceUpdate.key,
+                  );
+                  const parts: string[] = [];
+                  if (contextChanged || hostChanged || ipChanged) {
+                    const hostLabel = next.host?.trim() || "Unknown";
+                    const ipLabel = next.ip?.trim();
+                    parts.push(
+                      `Node: ${hostLabel}${ipLabel ? ` (${ipLabel})` : ""}`,
+                    );
+                  }
+                  if (versionChanged) {
+                    parts.push(`app ${next.version?.trim() || "unknown"}`);
+                  }
+                  if (modeChanged) {
+                    parts.push(`mode ${next.mode?.trim() || "unknown"}`);
+                  }
+                  if (reasonChanged) {
+                    parts.push(`reason ${reasonValue?.trim() || "event"}`);
+                  }
+                  const deltaText = parts.join(" · ");
+                  if (deltaText) {
+                    enqueueSystemEvent(deltaText, {
+                      contextKey: presenceUpdate.key,
+                    });
+                  }
+                }
+              } else {
+                enqueueSystemEvent(text);
               }
               presenceVersion += 1;
               broadcast(
@@ -4850,6 +4955,43 @@ export async function startGatewayServer(
     `gateway listening on ws://${bindHost}:${port} (PID ${process.pid})`,
   );
   defaultRuntime.log(`gateway log file: ${getResolvedLoggerSettings().file}`);
+  let tailscaleCleanup: (() => Promise<void>) | null = null;
+  if (tailscaleMode !== "off") {
+    try {
+      if (tailscaleMode === "serve") {
+        await enableTailscaleServe(port);
+      } else {
+        await enableTailscaleFunnel(port);
+      }
+      const host = await getTailnetHostname().catch(() => null);
+      if (host) {
+        logInfo(
+          `tailscale ${tailscaleMode} enabled: https://${host}/ui/ (WS via wss://${host})`,
+        );
+      } else {
+        logInfo(`tailscale ${tailscaleMode} enabled`);
+      }
+    } catch (err) {
+      logWarn(
+        `tailscale ${tailscaleMode} failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+    if (tailscaleConfig.resetOnExit) {
+      tailscaleCleanup = async () => {
+        try {
+          if (tailscaleMode === "serve") {
+            await disableTailscaleServe();
+          } else {
+            await disableTailscaleFunnel();
+          }
+        } catch (err) {
+          logWarn(
+            `tailscale ${tailscaleMode} cleanup failed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+        }
+      };
+    }
+  }
 
   // Start clawd browser control server (unless disabled via config).
   void startBrowserControlServerIfEnabled().catch((err) => {
@@ -4875,6 +5017,9 @@ export async function startGatewayServer(
           /* ignore */
         }
       }
+      if (tailscaleCleanup) {
+        await tailscaleCleanup();
+      }
       if (canvasHost) {
         try {
           await canvasHost.close();

src/infra/pam.ts

@@ -0,0 +1,61 @@
+type PamAuthenticate = (
+  username: string,
+  password: string,
+  callback: (err: Error | null) => void,
+) => void;
+
+let pamAuth: PamAuthenticate | null | undefined;
+let pamError: string | null = null;
+
+async function loadPam(): Promise<void> {
+  if (pamAuth !== undefined) return;
+  try {
+    // Vite/Vitest: avoid static analysis/bundling for optional native deps.
+    const pkgName = "authenticate-pam";
+    const mod = (await import(pkgName)) as
+      | { authenticate?: PamAuthenticate; default?: PamAuthenticate }
+      | PamAuthenticate;
+    const candidate =
+      typeof mod === "function"
+        ? mod
+        : typeof (mod as { authenticate?: PamAuthenticate }).authenticate ===
+            "function"
+          ? (mod as { authenticate: PamAuthenticate }).authenticate
+          : typeof (mod as { default?: PamAuthenticate }).default === "function"
+            ? (mod as { default: PamAuthenticate }).default
+            : null;
+    if (!candidate) {
+      throw new Error(
+        "authenticate-pam did not export an authenticate function",
+      );
+    }
+    pamAuth = candidate;
+  } catch (err) {
+    pamAuth = null;
+    pamError = err instanceof Error ? err.message : String(err);
+  }
+}
+
+export type PamAvailability = {
+  available: boolean;
+  error?: string;
+};
+
+export async function getPamAvailability(): Promise<PamAvailability> {
+  await loadPam();
+  return pamAuth
+    ? { available: true }
+    : { available: false, error: pamError ?? undefined };
+}
+
+export async function verifyPamCredentials(
+  username: string,
+  password: string,
+): Promise<boolean> {
+  await loadPam();
+  const auth = pamAuth;
+  if (!auth) return false;
+  return await new Promise<boolean>((resolve) => {
+    auth(username, password, (err) => resolve(!err));
+  });
+}

src/infra/system-events.ts

@@ -7,10 +7,30 @@ type SystemEvent = { text: string; ts: number };
 const MAX_EVENTS = 20;
 const queue: SystemEvent[] = [];
 let lastText: string | null = null;
+let lastContextKey: string | null = null;
 
-export function enqueueSystemEvent(text: string) {
+type SystemEventOptions = {
+  contextKey?: string | null;
+};
+
+function normalizeContextKey(key?: string | null): string | null {
+  if (!key) return null;
+  const trimmed = key.trim();
+  if (!trimmed) return null;
+  return trimmed.toLowerCase();
+}
+
+export function isSystemEventContextChanged(
+  contextKey?: string | null,
+): boolean {
+  const normalized = normalizeContextKey(contextKey);
+  return normalized !== lastContextKey;
+}
+
+export function enqueueSystemEvent(text: string, options?: SystemEventOptions) {
   const cleaned = text.trim();
   if (!cleaned) return;
+  lastContextKey = normalizeContextKey(options?.contextKey);
   if (lastText === cleaned) return; // skip consecutive duplicates
   lastText = cleaned;
   queue.push({ text: cleaned, ts: Date.now() });
@@ -21,6 +41,7 @@ export function drainSystemEvents(): string[] {
   const out = queue.map((e) => e.text);
   queue.length = 0;
   lastText = null;
+  lastContextKey = null;
   return out;
 }
 

src/infra/system-presence.ts

@@ -16,6 +16,14 @@ export type SystemPresence = {
   ts: number;
 };
 
+export type SystemPresenceUpdate = {
+  key: string;
+  previous?: SystemPresence;
+  next: SystemPresence;
+  changes: Partial<SystemPresence>;
+  changedKeys: (keyof SystemPresence)[];
+};
+
 const entries = new Map<string, SystemPresence>();
 const TTL_MS = 5 * 60 * 1000; // 5 minutes
 const MAX_ENTRIES = 200;
@@ -154,7 +162,9 @@ type SystemPresencePayload = {
   tags?: string[];
 };
 
-export function updateSystemPresence(payload: SystemPresencePayload) {
+export function updateSystemPresence(
+  payload: SystemPresencePayload,
+): SystemPresenceUpdate {
   ensureSelfPresence();
   const parsed = parsePresence(payload.text);
   const key =
@@ -164,6 +174,7 @@ export function updateSystemPresence(payload: SystemPresencePayload) {
     parsed.ip ||
     parsed.text.slice(0, 64) ||
     os.hostname().toLowerCase();
+  const hadExisting = entries.has(key);
   const existing = entries.get(key) ?? ({} as SystemPresence);
   const merged: SystemPresence = {
     ...existing,
@@ -185,6 +196,25 @@ export function updateSystemPresence(payload: SystemPresencePayload) {
     ts: Date.now(),
   };
   entries.set(key, merged);
+  const trackKeys = ["host", "ip", "version", "mode", "reason"] as const;
+  type TrackKey = (typeof trackKeys)[number];
+  const changes: Partial<Pick<SystemPresence, TrackKey>> = {};
+  const changedKeys: TrackKey[] = [];
+  for (const k of trackKeys) {
+    const prev = existing[k];
+    const next = merged[k];
+    if (prev !== next) {
+      changes[k] = next;
+      changedKeys.push(k);
+    }
+  }
+  return {
+    key,
+    previous: hadExisting ? existing : undefined,
+    next: merged,
+    changes,
+    changedKeys,
+  } satisfies SystemPresenceUpdate;
 }
 
 export function upsertPresence(key: string, presence: Partial<SystemPresence>) {

src/infra/tailscale.ts

@@ -181,3 +181,37 @@ export async function ensureFunnel(
     runtime.exit(1);
   }
 }
+
+export async function enableTailscaleServe(
+  port: number,
+  exec: typeof runExec = runExec,
+) {
+  await exec("tailscale", ["serve", "--bg", "--yes", `${port}`], {
+    maxBuffer: 200_000,
+    timeoutMs: 15_000,
+  });
+}
+
+export async function disableTailscaleServe(exec: typeof runExec = runExec) {
+  await exec("tailscale", ["serve", "reset"], {
+    maxBuffer: 200_000,
+    timeoutMs: 15_000,
+  });
+}
+
+export async function enableTailscaleFunnel(
+  port: number,
+  exec: typeof runExec = runExec,
+) {
+  await exec("tailscale", ["funnel", "--bg", "--yes", `${port}`], {
+    maxBuffer: 200_000,
+    timeoutMs: 15_000,
+  });
+}
+
+export async function disableTailscaleFunnel(exec: typeof runExec = runExec) {
+  await exec("tailscale", ["funnel", "reset"], {
+    maxBuffer: 200_000,
+    timeoutMs: 15_000,
+  });
+}

src/media/store.header-ext.test.ts

@@ -0,0 +1,38 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
+
+const realOs = await vi.importActual<typeof import("node:os")>("node:os");
+const HOME = path.join(realOs.tmpdir(), "clawdis-home-header-ext-test");
+
+vi.mock("node:os", () => ({
+  default: { homedir: () => HOME, tmpdir: () => realOs.tmpdir() },
+  homedir: () => HOME,
+  tmpdir: () => realOs.tmpdir(),
+}));
+
+vi.mock("./mime.js", async () => {
+  const actual = await vi.importActual<typeof import("./mime.js")>("./mime.js");
+  return {
+    ...actual,
+    detectMime: vi.fn(async () => "audio/opus"),
+  };
+});
+
+const store = await import("./store.js");
+
+describe("media store header extensions", () => {
+  beforeAll(async () => {
+    await fs.rm(HOME, { recursive: true, force: true });
+  });
+
+  afterAll(async () => {
+    await fs.rm(HOME, { recursive: true, force: true });
+  });
+
+  it("prefers header mime extension when sniffed mime lacks mapping", async () => {
+    const buf = Buffer.from("fake-audio");
+    const saved = await store.saveMediaBuffer(buf, "audio/ogg; codecs=opus");
+    expect(path.extname(saved.path)).toBe(".ogg");
+  });
+});

src/media/store.ts

@@ -169,8 +169,11 @@ export async function saveMediaBuffer(
   const dir = path.join(MEDIA_DIR, subdir);
   await fs.mkdir(dir, { recursive: true });
   const baseId = crypto.randomUUID();
+  const headerExt = extensionForMime(
+    contentType?.split(";")[0]?.trim() ?? undefined,
+  );
   const mime = await detectMime({ buffer, headerMime: contentType });
-  const ext = extensionForMime(mime);
+  const ext = headerExt ?? extensionForMime(mime);
   const id = ext ? `${baseId}${ext}` : baseId;
   const dest = path.join(dir, id);
   await fs.writeFile(dest, buffer);