Overhaul bootstrap UX: CWD-independent config discovery, wizard resume + preflight, Telegram pairing, Bedrock region prefixes (#112)

Author: pufit

config.example.yaml

@@ -36,7 +36,14 @@ gateway:
 # Channels
 telegram:
   enabled: true
-  dm_policy: pairing             # "open" or "pairing" (require pairing code)
+  # DM authorization:
+  #   pairing — only users in allowed_users may talk to the bot. New users
+  #             authorize with a one-time code: run `nerve pair` on the
+  #             server, then send the bot `/pair <code>`. Paired IDs are
+  #             persisted to config.local.yaml automatically.
+  #   open    — anyone can talk to the bot (dangerous: full agent access).
+  dm_policy: pairing
+  # allowed_users: [123456789]   # numeric Telegram user IDs (or pair instead)
   stream_mode: partial           # "partial" (edit messages) or "full" (wait for complete)
 
 # Quiet hours (local timezone)

docs/config.md

@@ -5,6 +5,22 @@ Nerve uses two YAML config files:
 - `config.local.yaml` — Secrets and personal overrides (gitignored)
 
 Values in `config.local.yaml` are deep-merged on top of `config.yaml`.
+Unknown keys are ignored but logged as warnings at startup (and shown by
+`nerve doctor`) so typos don't fail silently.
+
+## Config Directory Resolution
+
+`nerve` commands locate the config directory via a waterfall, so they work
+from any working directory:
+
+1. `--config-dir` / `-c` flag
+2. `NERVE_CONFIG_DIR` environment variable
+3. The current directory, if it contains `config.yaml` or `config.local.yaml`
+4. The pointer file `~/.nerve/config_dir` (written by `nerve init` and on
+   daemon start)
+5. The current directory (fresh-install fallback)
+
+`nerve doctor` reports which directory was used and how it was found.
 
 ## Core
 
@@ -42,9 +58,27 @@ Values in `config.local.yaml` are deep-merged on top of `config.yaml`.
 |-----|------|---------|-------------|
 | `telegram.enabled` | bool | `true` | Enable Telegram bot |
 | `telegram.bot_token` | string | - | Bot token from @BotFather |
-| `telegram.dm_policy` | string | `pairing` | `open` or `pairing` |
+| `telegram.dm_policy` | string | `pairing` | `pairing` (allowlist + one-time pairing codes) or `open` (anyone — dangerous) |
+| `telegram.allowed_users` | list[int] | `[]` | Telegram user IDs allowed to DM the bot |
 | `telegram.stream_mode` | string | `partial` | `partial` (edit msgs) or `full` |
 
+### Pairing
+
+With `dm_policy: pairing` (the default), the bot only talks to users in
+`allowed_users` and rejects everyone else. To authorize a user without
+editing config files:
+
+1. Run `nerve pair` on the server — it prints a one-time 6-digit code
+   (valid 1 hour). On a fresh install with no `allowed_users`, a code is
+   also generated automatically at startup and printed to the log.
+2. Send the bot `/pair <code>` from the Telegram account to authorize.
+3. The user ID is appended to `telegram.allowed_users` in
+   `config.local.yaml` and takes effect immediately.
+
+An unauthorized `/start` gets a reply with the sender's numeric ID and
+pairing instructions (rate-limited); all other messages from unauthorized
+users are ignored.
+
 ## Quiet Hours
 
 | Key | Type | Default | Description |

install.sh

@@ -65,6 +65,23 @@ get_python_version() {
 
 trap 'error "Installation failed at line $LINENO. See above for details."' ERR
 
+# A clean message on Ctrl+C / SIGTERM beats silent death: tell the user
+# what state they're in and how to continue.
+on_interrupt() {
+    trap - INT TERM ERR
+    printf "\n"
+    warn "Interrupted."
+    if [ "${INSTALL_DONE:-0}" = "1" ]; then
+        info "Installation itself is complete — finish setup anytime with: nerve init"
+        info "(setup answers are saved; it resumes where you left off)"
+    else
+        info "Re-run the installer to continue — completed steps are skipped."
+    fi
+    exit 130
+}
+trap on_interrupt INT TERM
+INSTALL_DONE=0
+
 # --- OS Detection ---
 
 detect_os() {
@@ -450,20 +467,66 @@ setup_path() {
 
 # --- Run nerve init ---
 
-run_init() {
-    step "Running Nerve setup"
+INIT_COMPLETED=0
+INIT_SKIPPED=0
 
+run_init() {
     local nerve_bin="$INSTALL_DIR/.venv/bin/nerve"
     local config_local="$INSTALL_DIR/config.local.yaml"
 
     if [ "$IS_UPGRADE" = "1" ] && [ -f "$config_local" ]; then
         info "Existing configuration found — skipping setup wizard"
         info "Run 'nerve init' to reconfigure"
+        INIT_COMPLETED=1
+        return
+    fi
+
+    # Clear boundary between installation and configuration: everything is
+    # installed at this point — the wizard is optional and resumable.
+    printf "\n"
+    printf "${BOLD}${GREEN}  Installation complete.${NC}\n"
+    printf "\n"
+    printf "  Next: an interactive setup wizard configures your API keys,\n"
+    printf "  workspace, and channels. It takes a few minutes; Ctrl+C is\n"
+    printf "  safe — answers are saved and ${BOLD}nerve init${NC} resumes later.\n"
+    printf "\n"
+
+    if ! confirm "Run the setup wizard now?"; then
+        info "Skipping setup. Run it later with: nerve init"
+        INIT_SKIPPED=1
         return
     fi
 
+    step "Running Nerve setup"
     cd "$INSTALL_DIR" || exit 1
-    "$nerve_bin" init
+    # Don't let a wizard abort look like a failed installation (set -e).
+    if "$nerve_bin" init; then
+        INIT_COMPLETED=1
+    else
+        printf "\n"
+        warn "Setup did not finish. Installation itself is complete."
+        info "Resume setup anytime with: nerve init"
+        INIT_SKIPPED=1
+    fi
+}
+
+# --- Offer to start the daemon ---
+
+offer_start() {
+    # Only when freshly configured and interactive
+    if [ "$INIT_COMPLETED" != "1" ] || [ "$IS_UPGRADE" = "1" ]; then
+        return
+    fi
+    printf "\n"
+    if ! confirm "Start Nerve now?"; then
+        return
+    fi
+    local nerve_bin="$INSTALL_DIR/.venv/bin/nerve"
+    if "$nerve_bin" start; then
+        NERVE_STARTED=1
+    else
+        warn "Start failed — check logs with: nerve logs"
+    fi
 }
 
 # --- Summary ---
@@ -478,6 +541,14 @@ print_summary() {
     if [ "$IS_UPGRADE" = "1" ]; then
         printf "  ${BOLD}Upgrade complete.${NC} Restart to apply changes:\n"
         printf "    ${CYAN}nerve restart${NC}\n"
+    elif [ "${NERVE_STARTED:-0}" = "1" ]; then
+        printf "  ${BOLD}Nerve is running.${NC}\n"
+        printf "    ${CYAN}http://localhost:8900${NC}     Open the web UI\n"
+        printf "    ${CYAN}nerve logs${NC}            Follow daemon logs\n"
+    elif [ "$INIT_SKIPPED" = "1" ]; then
+        printf "  ${BOLD}Finish setup, then start:${NC}\n"
+        printf "    ${CYAN}nerve init${NC}            Resume the setup wizard\n"
+        printf "    ${CYAN}nerve start${NC}           Start as daemon\n"
     else
         printf "  ${BOLD}Get started:${NC}\n"
         printf "    ${CYAN}nerve start${NC}           Start as daemon\n"
@@ -502,6 +573,7 @@ print_summary() {
         warn "nerve is not yet on PATH in this shell session"
         printf "  Run: ${BOLD}source ~/.bashrc${NC}  (or restart your terminal)\n\n"
     fi
+    printf "  ${DIM}Installer finished — you can close this terminal.${NC}\n\n"
 }
 
 # --- Usage ---
@@ -564,8 +636,11 @@ main() {
     setup_python_env
     build_web_ui
     setup_path
+    INSTALL_DONE=1
     run_init
+    offer_start
     print_summary
+    exit 0
 }
 
 main "$@"