@rubytech/create-realagent 1.0.615 → 1.0.617

package/payload/platform/scripts/logs-read.sh

@@ -1,19 +1,28 @@
 #!/usr/bin/env bash
 # logs-read.sh — Shell counterpart to the logs-read MCP tool.
 #
-# Mirrors the MCP tool's exact behaviour so the dev agent can retrieve
-# session logs from the Pi over SSH with one call instead of constructing
-# ad-hoc grep pipelines.
+# Task 532: stream logs are per-conversation, not per-day. The primary mode
+# now reads a single {prefix}-{conversationId}.log file — the reader gets a
+# continuous, conversation-scoped timeline from first [spawn] to final
+# [process-exit] without needing to filter.
 #
-# Usage:
-#   logs-read.sh <sessionKey> [type]       Session-key mode (grep across log files)
-#   logs-read.sh --tail [type] [lines]     Tail most recent file of specified type
+# Modes:
+#   logs-read.sh <conversationId> [type]       Read {prefix}-{convId}.log
+#   logs-read.sh --tail [type] [lines]         Tail most recent file of type
+#   logs-read.sh --grep <sessionKey> [type]    Legacy grep across log files
 #
-# Types: system, session, error, heartbeat, public, server
+# Types: system, session, error, heartbeat, public, server, mcp, vnc, review
+# For per-conversation types (system/session/error/public): conversationId is
+# required in the first mode. For platform-scoped types (server/vnc/review/
+# heartbeat): conversationId is ignored.
+#
+# Every invocation writes a one-line trailer describing files searched,
+# matches returned, and files rejected — empty output never leaves a reader
+# guessing why.
 #
 # Exit codes:
 #   0  Success (output produced)
-#   1  No matches found (clean, not an error)
+#   1  No matches / file not found (clean, not an error)
 #   2  Usage error or missing directory
 set -euo pipefail
 
@@ -50,7 +59,6 @@ if [[ ${#ACCOUNT_DIRS[@]} -eq 0 ]]; then
 fi
 
 # Build array of account log directories that actually exist.
-# Multi-account devices (e.g. Maxy Pi) may have >1 account dir.
 ACCOUNT_LOG_DIRS=()
 for _adir in "${ACCOUNT_DIRS[@]}"; do
   [[ -d "${_adir}logs" ]] && ACCOUNT_LOG_DIRS+=("${_adir}logs")
@@ -62,20 +70,15 @@ fi
 MULTI_ACCOUNT=$(( ${#ACCOUNT_LOG_DIRS[@]} > 1 ? 1 : 0 ))
 
 # Account ID suffix for headers — only shown when multiple accounts exist.
-# Accepts a log directory path (e.g. /path/accounts/<id>/logs) and extracts
-# the account ID from the parent directory name.
 account_suffix() {
   if [[ $MULTI_ACCOUNT -eq 1 ]]; then
     local path="$1"
-    # Normalize: strip trailing slash, ensure we're looking at the logs dir
     path="${path%/}"
-    # If path ends with /logs, extract account ID from parent
     if [[ "$path" == */logs ]]; then
       local acct_id
       acct_id=$(basename "$(dirname "$path")")
       echo " [${acct_id:0:8}]"
     else
-      # Path is a file inside logs/ — go up two levels
       local acct_id
       acct_id=$(basename "$(dirname "$(dirname "$path")")")
       echo " [${acct_id:0:8}]"
@@ -84,7 +87,7 @@ account_suffix() {
 }
 
 # --- Prefix map (mirrors MCP tool exactly) ---
-# Function instead of associative array for bash 3.x compatibility (macOS testing).
+# Per-conversation types: stream log + its siblings (stderr, sse, public).
 prefix_for_type() {
   case "$1" in
     system)  echo "claude-agent-stream-" ;;
@@ -96,24 +99,34 @@ prefix_for_type() {
   esac
 }
 
-# All searchable types (excludes heartbeat — no session context in heartbeat logs)
+# Which types are per-conversation (the first mode's convId argument applies)
+is_per_conversation_type() {
+  case "$1" in
+    system|error|session|public) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+
 SEARCH_TYPES="system error session public server mcp vnc review"
 VALID_TYPES="system, session, error, heartbeat, public, server, mcp, vnc, review"
 
-# --- Usage ---
 usage() {
   cat >&2 <<EOF
 Usage:
-  logs-read.sh <sessionKey> [type]       Grep logs for session key
-  logs-read.sh --tail [type] [lines]     Tail most recent log file
+  logs-read.sh <conversationId> [type]       Read {prefix}-{convId}.log
+  logs-read.sh --tail [type] [lines]         Tail most recent log of type
+  logs-read.sh --grep <sessionKey> [type]    Legacy grep across log files
 
 Types: $VALID_TYPES
 Default type: system | Default lines: 50
+
+Per-conversation types (system, session, error, public) require conversationId
+in the first mode — the log file is named {prefix}-{conversationId}.log.
+Platform-scoped types (server, vnc, review, heartbeat) ignore conversationId.
 EOF
   exit 2
 }
 
-# --- Validate type ---
 validate_type() {
   local t="$1"
   case "$t" in
@@ -122,12 +135,65 @@ validate_type() {
   esac
 }
 
-# --- Session-key mode ---
-session_key_mode() {
+# --- Per-conversation mode: read {prefix}-{convId}.log ---
+per_conversation_mode() {
+  local conv_id="$1"
+  local filter_type="${2:-system}"
+
+  if [[ -z "$conv_id" ]]; then
+    echo "Error: conversationId cannot be empty" >&2
+    exit 2
+  fi
+
+  validate_type "$filter_type"
+
+  # Platform-scoped types shortcut to their fixed files regardless of convId.
+  case "$filter_type" in
+    server|vnc|review|heartbeat|mcp)
+      echo "# note: type=$filter_type is platform-scoped; conversationId ignored — showing fixed file" >&2
+      tail_mode "$filter_type" "50"
+      return
+      ;;
+  esac
+
+  local prefix
+  prefix=$(prefix_for_type "$filter_type")
+  if [[ -z "$prefix" ]]; then
+    echo "Error: no prefix mapping for type '$filter_type'" >&2
+    exit 2
+  fi
+
+  local found=0
+  local searched=0
+  local rejected=0
+  for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
+    local filepath="$log_dir/${prefix}${conv_id}.log"
+    searched=$((searched + 1))
+    if [[ ! -f "$filepath" ]]; then
+      rejected=$((rejected + 1))
+      continue
+    fi
+    [[ $found -gt 0 ]] && echo ""
+    echo "## $(basename "$filepath") ($filter_type)$(account_suffix "$log_dir")"
+    cat "$filepath"
+    found=$((found + 1))
+  done
+
+  # Trailer: empty output never leaves the reader guessing why.
+  if [[ $found -eq 0 ]]; then
+    echo "-- trailer: conversationId=$conv_id type=$filter_type searched=$searched found=0 rejected=$rejected reason=file-not-found" >&2
+    exit 1
+  fi
+  echo "" >&2
+  echo "-- trailer: conversationId=$conv_id type=$filter_type searched=$searched matched=$found rejected=$rejected" >&2
+  exit 0
+}
+
+# --- Legacy grep mode (backward compatibility with sessionKey-tagged lines) ---
+grep_mode() {
   local session_key="$1"
   local filter_type="${2:-}"
 
-  # Guard against empty session key (grep -F "" matches everything)
   if [[ -z "$session_key" ]]; then
     echo "Error: session key cannot be empty" >&2
     exit 2
@@ -137,7 +203,6 @@ session_key_mode() {
     validate_type "$filter_type"
   fi
 
-  # Determine which types to search
   local types_to_search
   if [[ -n "$filter_type" && "$filter_type" != "heartbeat" ]]; then
     types_to_search="$filter_type"
@@ -146,11 +211,13 @@ session_key_mode() {
   fi
 
   local found=0
+  local files_searched=0
+  local files_rejected=0
 
   for log_type in $types_to_search; do
-    # server: single file in configDir (platform-scoped, not account-scoped)
     if [[ "$log_type" == "server" ]]; then
       if [[ -f "$SERVER_LOG" ]]; then
+        files_searched=$((files_searched + 1))
         local result
         if result=$(grep -F "$session_key" "$SERVER_LOG" 2>/dev/null); then
           if [[ -n "$result" ]]; then
@@ -160,14 +227,15 @@ session_key_mode() {
             found=$((found + 1))
           fi
         fi
+      else
+        files_rejected=$((files_rejected + 1))
       fi
       continue
     fi
 
-    # vnc: single platform-scoped file covering the VNC browser viewer
-    # lifecycle (boot events from vnc.sh + runtime events from vnc-logger.ts)
     if [[ "$log_type" == "vnc" ]]; then
       if [[ -f "$VNC_LOG" ]]; then
+        files_searched=$((files_searched + 1))
         local result
         if result=$(grep -F "$session_key" "$VNC_LOG" 2>/dev/null); then
           if [[ -n "$result" ]]; then
@@ -177,16 +245,15 @@ session_key_mode() {
             found=$((found + 1))
           fi
         fi
+      else
+        files_rejected=$((files_rejected + 1))
       fi
       continue
     fi
 
-    # review: single platform-scoped file containing every decision made
-    # by the in-process review detector — scan cycles, matches, suppressions,
-    # rate-limit decisions, rule mutations, and admin tool audit trail.
-    # Task 385 — the one log that proves observability-plus-review is working.
     if [[ "$log_type" == "review" ]]; then
       if [[ -f "$REVIEW_LOG" ]]; then
+        files_searched=$((files_searched + 1))
         local result
         if result=$(grep -F "$session_key" "$REVIEW_LOG" 2>/dev/null); then
           if [[ -n "$result" ]]; then
@@ -196,6 +263,8 @@ session_key_mode() {
             found=$((found + 1))
           fi
         fi
+      else
+        files_rejected=$((files_rejected + 1))
       fi
       continue
     fi
@@ -204,20 +273,17 @@ session_key_mode() {
     prefix=$(prefix_for_type "$log_type")
     [[ -z "$prefix" ]] && continue
 
-    # Search all account log directories for matching files
     for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
       shopt -s nullglob
       local files=("$log_dir"/${prefix}*.log)
       shopt -u nullglob
-
-      # Sort by filename (date suffix ensures chronological order)
       IFS=$'\n' files=($(printf '%s\n' "${files[@]}" | sort)); unset IFS
 
       for filepath in "${files[@]}"; do
+        files_searched=$((files_searched + 1))
         local file
         file=$(basename "$filepath")
 
-        # grep -F: fixed string match. Exit 1 = no match (expected).
         local result
         if result=$(grep -F "$session_key" "$filepath" 2>/dev/null); then
           if [[ -n "$result" ]]; then
@@ -232,27 +298,26 @@ session_key_mode() {
   done
 
   if [[ $found -eq 0 ]]; then
-    echo "No log lines found for session key \"$session_key\"."
+    echo "No log lines found for session key \"$session_key\"." >&2
+    echo "-- trailer: sessionKey=$session_key files_searched=$files_searched files_rejected=$files_rejected matches=0" >&2
     exit 1
   fi
-
+  echo "" >&2
+  echo "-- trailer: sessionKey=$session_key files_searched=$files_searched files_rejected=$files_rejected matches=$found" >&2
   exit 0
 }
 
-# --- Tail mode ---
 tail_mode() {
   local log_type="${1:-system}"
   local lines="${2:-50}"
 
   validate_type "$log_type"
 
-  # Validate lines is numeric
   if ! [[ "$lines" =~ ^[0-9]+$ ]]; then
     echo "Error: lines must be a number, got '$lines'" >&2
     exit 2
   fi
 
-  # Heartbeat: single fixed file (account-scoped) — search all accounts, use most recent
   if [[ "$log_type" == "heartbeat" ]]; then
     local hb_file=""
     for log_dir in "${ACCOUNT_LOG_DIRS[@]}"; do
@@ -273,7 +338,6 @@ tail_mode() {
     exit 0
   fi
 
-  # Server: single fixed file (platform-scoped, in configDir)
   if [[ "$log_type" == "server" ]]; then
     if [[ ! -f "$SERVER_LOG" ]]; then
       echo "No server log found at $SERVER_LOG"
@@ -285,11 +349,6 @@ tail_mode() {
     exit 0
   fi
 
-  # VNC: single platform-scoped file covering the entire VNC browser
-  # viewer lifecycle (Xtigervnc boot, websockify, Chromium CDP, HTTP
-  # viewer fetches, WebSocket upgrades, proxy pipe events, MCP browser
-  # tool calls, client disconnect reasons, ensureVnc/ensureCdp recovery).
-  # Single retrieval must diagnose any browser-viewer failure mode.
   if [[ "$log_type" == "vnc" ]]; then
     if [[ ! -f "$VNC_LOG" ]]; then
       echo "No vnc-boot log found at $VNC_LOG"
@@ -301,10 +360,6 @@ tail_mode() {
     exit 0
   fi
 
-  # Review: single platform-scoped file written by the review detector
-  # (Task 385). Every scan cycle, rule match, suppression decision, rate
-  # limit hold-back, and admin-tool rule mutation is logged here. This is
-  # the canonical log to audit "did the detector see this?" questions.
   if [[ "$log_type" == "review" ]]; then
     if [[ ! -f "$REVIEW_LOG" ]]; then
       echo "No review log found at $REVIEW_LOG (detector may not have started yet)"
@@ -316,7 +371,6 @@ tail_mode() {
     exit 0
   fi
 
-  # Find most recent file by mtime across all account log directories
   local prefix
   prefix=$(prefix_for_type "$log_type")
 
@@ -333,7 +387,9 @@ tail_mode() {
     exit 1
   fi
 
-  # Sort by mtime descending — most recent first
+  # Sort by mtime descending — most recent first. Per-conversation filenames
+  # no longer sort chronologically by name (UUID suffix), so mtime is the
+  # only reliable "most recently active" ordering.
   local match
   match=$(ls -t "${all_files[@]}" | head -1)
   local match_name
@@ -345,7 +401,6 @@ tail_mode() {
   exit 0
 }
 
-# --- Main ---
 if [[ $# -eq 0 ]]; then
   usage
 fi
@@ -355,6 +410,11 @@ case "$1" in
     shift
     tail_mode "${1:-system}" "${2:-50}"
     ;;
+  --grep)
+    shift
+    [[ $# -eq 0 ]] && usage
+    grep_mode "$1" "${2:-}"
+    ;;
   --help|-h)
     usage
     ;;
@@ -363,6 +423,6 @@ case "$1" in
     usage
     ;;
   *)
-    session_key_mode "$1" "${2:-}"
+    per_conversation_mode "$1" "${2:-}"
     ;;
 esac

package/payload/platform/templates/specialists/agents/personal-assistant.md

@@ -3,7 +3,7 @@ name: personal-assistant
 description: "Your personal assistant — scheduling, platform administration, messaging channels, system health, and browser automation. Delegate when a task involves managing your calendar, configuring the platform, operating messaging channels, or completing interactive browser tasks."
 summary: "Handles the operational tasks you'd give a personal assistant — scheduling meetings, managing your platform settings, connecting messaging channels, and completing browser-based tasks on your behalf. For example, when you want to schedule a weekly check-in, set up Telegram, or fill out an online form."
 model: claude-sonnet-4-6
-tools: mcp__admin__system-status, mcp__admin__brand-settings, mcp__admin__account-manage, mcp__admin__account-update, mcp__admin__logs-read, mcp__admin__plugin-read, mcp__admin__api-key-store, mcp__admin__api-key-verify, mcp__admin__render-component, mcp__admin__file-attach, mcp__admin__wifi, mcp__contacts__contact-create, mcp__contacts__contact-lookup, mcp__contacts__contact-update, mcp__contacts__contact-delete, mcp__contacts__contact-list, mcp__contacts__contact-export, mcp__contacts__contact-erase, mcp__contacts__group-create, mcp__contacts__group-manage, mcp__cloudflare__cf-set-token, mcp__cloudflare__cf-add-zone, mcp__cloudflare__cf-zone-status, mcp__cloudflare__tunnel-status, mcp__cloudflare__tunnel-install, mcp__cloudflare__tunnel-login, mcp__cloudflare__tunnel-create, mcp__cloudflare__tunnel-enable, mcp__cloudflare__tunnel-disable, mcp__cloudflare__tunnel-add-hostname, mcp__cloudflare__dns-lookup, mcp__telegram__message, mcp__telegram__message-history, mcp__telegram__telegram-webhook-register, mcp__whatsapp__whatsapp-login-start, mcp__whatsapp__whatsapp-login-wait, mcp__whatsapp__whatsapp-status, mcp__whatsapp__whatsapp-disconnect, mcp__whatsapp__whatsapp-send, mcp__whatsapp__whatsapp-send-document, mcp__whatsapp__whatsapp-config, mcp__whatsapp__whatsapp-activity, mcp__whatsapp__whatsapp-conversations, mcp__whatsapp__whatsapp-messages, mcp__whatsapp__whatsapp-group-info, mcp__email__email-setup, mcp__email__email-read, mcp__email__email-send, mcp__email__email-reply, mcp__email__email-search, mcp__email__email-graph-query, mcp__email__email-otp-extract, mcp__email__email-status, mcp__email__email-auto-respond-config, mcp__scheduling__schedule-event, mcp__scheduling__schedule-list, mcp__scheduling__schedule-get, mcp__scheduling__schedule-update, mcp__scheduling__schedule-cancel, mcp__scheduling__schedule-export-ics, mcp__scheduling__schedule-import-ics, mcp__scheduling__time-resolve, mcp__memory__memory-search, mcp__memory__profile-update, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_navigate_back, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_press_key, mcp__plugin_playwright_playwright__browser_hover, mcp__plugin_playwright_playwright__browser_select_option, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_handle_dialog, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_tabs, mcp__plugin_playwright_playwright__browser_close
+tools: mcp__admin__system-status, mcp__admin__brand-settings, mcp__admin__account-manage, mcp__admin__account-update, mcp__admin__logs-read, mcp__admin__plugin-read, mcp__admin__api-key-store, mcp__admin__api-key-verify, mcp__admin__render-component, mcp__admin__file-attach, mcp__admin__wifi, mcp__contacts__contact-create, mcp__contacts__contact-lookup, mcp__contacts__contact-update, mcp__contacts__contact-delete, mcp__contacts__contact-list, mcp__contacts__contact-export, mcp__contacts__contact-erase, mcp__contacts__group-create, mcp__contacts__group-manage, mcp__cloudflare__cf-add-zone, mcp__cloudflare__cf-zone-status, mcp__cloudflare__cf-verify, mcp__cloudflare__cf-rebuild, mcp__cloudflare__tunnel-status, mcp__cloudflare__tunnel-install, mcp__cloudflare__tunnel-login, mcp__cloudflare__tunnel-create, mcp__cloudflare__tunnel-enable, mcp__cloudflare__tunnel-disable, mcp__cloudflare__tunnel-add-hostname, mcp__cloudflare__dns-lookup, mcp__telegram__message, mcp__telegram__message-history, mcp__telegram__telegram-webhook-register, mcp__whatsapp__whatsapp-login-start, mcp__whatsapp__whatsapp-login-wait, mcp__whatsapp__whatsapp-status, mcp__whatsapp__whatsapp-disconnect, mcp__whatsapp__whatsapp-send, mcp__whatsapp__whatsapp-send-document, mcp__whatsapp__whatsapp-config, mcp__whatsapp__whatsapp-activity, mcp__whatsapp__whatsapp-conversations, mcp__whatsapp__whatsapp-messages, mcp__whatsapp__whatsapp-group-info, mcp__email__email-setup, mcp__email__email-read, mcp__email__email-send, mcp__email__email-reply, mcp__email__email-search, mcp__email__email-graph-query, mcp__email__email-otp-extract, mcp__email__email-status, mcp__email__email-auto-respond-config, mcp__scheduling__schedule-event, mcp__scheduling__schedule-list, mcp__scheduling__schedule-get, mcp__scheduling__schedule-update, mcp__scheduling__schedule-cancel, mcp__scheduling__schedule-export-ics, mcp__scheduling__schedule-import-ics, mcp__scheduling__time-resolve, mcp__memory__memory-search, mcp__memory__profile-update, mcp__plugin_playwright_playwright__browser_navigate, mcp__plugin_playwright_playwright__browser_navigate_back, mcp__plugin_playwright_playwright__browser_snapshot, mcp__plugin_playwright_playwright__browser_click, mcp__plugin_playwright_playwright__browser_fill, mcp__plugin_playwright_playwright__browser_fill_form, mcp__plugin_playwright_playwright__browser_type, mcp__plugin_playwright_playwright__browser_press_key, mcp__plugin_playwright_playwright__browser_hover, mcp__plugin_playwright_playwright__browser_select_option, mcp__plugin_playwright_playwright__browser_wait_for, mcp__plugin_playwright_playwright__browser_handle_dialog, mcp__plugin_playwright_playwright__browser_evaluate, mcp__plugin_playwright_playwright__browser_console_messages, mcp__plugin_playwright_playwright__browser_resize, mcp__plugin_playwright_playwright__browser_tabs, mcp__plugin_playwright_playwright__browser_close
 ---
 
 # Personal Assistant
@@ -41,19 +41,23 @@ Manages events, appointments, and recurring triggers in the graph.
 
 ## Cloudflare Tunnel
 
-Guides setting up a Cloudflare Tunnel so the platform is reachable via a custom domain. All operations are deterministic MCP tool calls.
+Guides setting up a Cloudflare Tunnel so the platform is reachable via a custom domain. The brand declares its Cloudflare zones at build time in `brand.json` (`cloudflare.zones`); every tool refuses operations against hostnames whose registrable parent is not in that list. Authentication is OAuth-only via `tunnel-login`; on first success the device records an account binding (`account-binding.json`) and refuses subsequent operations if the cert is later rotated under a different Cloudflare account.
 
-**Auth paths:** `tunnel-login` (one-click OAuth in VNC browser — preferred) or `cf-set-token` (user pastes an API token). Always check `tunnel-status` first to assess the current state. Both are idempotent.
+**Auth path:** `tunnel-login` (one-click OAuth in VNC browser). Pass `force=true` to clear cert + binding when switching Cloudflare accounts. There is no API-token auth path — the plugin recognises only the cert-bound account identity.
 
-**Setup flow:** Check status → authenticate → check/add zone → update nameservers at registrar → create tunnel → enable with remote password → verify URLs via browser. Not all steps are needed every time — start from wherever the current state is.
+**Setup flow:** `cloudflare-setup` is the single orchestrator — it discovers state, prompts for tunnel/zone selection and labels via UI components, then creates the tunnel and routes DNS for the declared zones.
 
-**DNS:** `cf-add-zone` adds a domain to Cloudflare. `cf-zone-status` checks whether nameservers have propagated. Nameservers are the #1 troubleshooting issue. `dns-lookup` verifies DNS resolution for a hostname.
+**Diagnostic flow:** `cf-verify` audits every relevant Cloudflare artefact and tags each as IN-SCOPE / OUT-OF-SCOPE / MISSING against the brand manifest and account binding. Non-mutating; safe to run at any time, including before login.
 
-**Tunnel lifecycle:** `tunnel-create` creates a tunnel + default hostname route. `tunnel-enable` starts the tunnel daemon with a remote management password. `tunnel-disable` stops it. `tunnel-add-hostname` adds additional routes for alias domains.
+**Recovery flow:** `cf-rebuild` discards out-of-scope artefacts and reconstructs the declared state. Idempotent. Refuses to delete cert.pem when bound to the wrong account; halts with an actionable instruction to run `tunnel-login force=true`. Pass `dryRun=true` to preview.
 
-**User-facing language:** Say "connection" not "API token", "domain" not "zone", "domain routing" not "DNS". No Cloudflare internal terminology.
+**DNS lookups:** `dns-lookup` for hostname resolution. Nameserver-not-yet-propagated is the most common operator issue; `cf-zone-status` reports activation status.
 
-**Verification:** Always verify URLs actually work by navigating to them in the browser. Never claim a URL works without browser verification.
+**Alias domains:** `tunnel-add-hostname` registers an additional declared zone as an alias on an existing tunnel. The hostname must still be in scope per `brand.cloudflare.zones`.
+
+**User-facing language:** Say "connection" not "certificate", "domain" not "zone", "address" not "hostname". No Cloudflare internal terminology.
+
+**Verification:** Always verify URLs work by navigating to them in the browser. Never claim a URL works without browser verification.
 
 ## Telegram