Align ISO config docs with post-install setup

build.cfg

@@ -33,7 +33,6 @@ IMAGE_SIZE="50G"
 # post-install setup/token flow. Use --clawdie-version X.Y.Z for release builds.
 CLAWDIE_VERSION="main"
 CLAWDIE_REF="${CLAWDIE_REF:-main}"
-CLAWDIE_TARBALL_URL="https://codeberg.org/Clawdie/Clawdie-AI/archive/${CLAWDIE_REF}.tar.gz"
 
 # Default installer choices (can be overridden by setup.txt on the writable USB config partition)
 DEFAULT_PKG_BRANCH="latest"     # latest or quarterly
@@ -53,7 +52,7 @@ AGENT_DOMAIN="${AGENT_DOMAIN:-}"
 AGENT_GENDER="${AGENT_GENDER:-}"
 TZ="${TZ:-}"
 
-# LLM provider (default: zai with glm-5)
+# LLM provider/model. Leave blank for post-install setup and Clawdie-AI profile defaults.
 PI_TUI_PROVIDER="${PI_TUI_PROVIDER:-}"
 PI_TUI_MODEL="${PI_TUI_MODEL:-}"
 
@@ -62,7 +61,8 @@ ZAI_API_KEY="${ZAI_API_KEY:-}"
 OPENROUTER_API_KEY="${OPENROUTER_API_KEY:-}"
 ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
 
-# Embeddings (default: OpenRouter with bge-m3)
+# Embeddings. Leave base URL blank to let Clawdie-AI choose OpenRouter when
+# OPENROUTER_API_KEY is present, otherwise local llama-server.
 EMBED_BASE_URL="${EMBED_BASE_URL:-}"
 EMBED_MODEL="${EMBED_MODEL:-}"
 EMBED_API_KEY="${EMBED_API_KEY:-}"

docs/VPS-MIGRATION.md

@@ -1,149 +1,76 @@
-# Clawdie-VPS — Linux→FreeBSD Migration for VPS
+# VPS / Cloud Deployment Notes
 
-**Status:** Ready for testing — 2026-03-18
+**Status:** experimental / legacy path. The primary validation target is the
-**Target:** Vultr, Hetzner, OVH, any VPS with custom ISO support
+unified ISO live installer. VPS/cloud deployment remains supported as a design
+goal, but the scripts under `vps/` have not yet been brought fully in line with
+the current post-install `/setup` flow.
+
+Use this page as orientation, not as a release checklist.
 
 ---
 
-## Quick Start (Vultr)
+## Current Direction
 
-### Step 1: Upload mfsBSD ISO
+The target VPS flow should match the ISO contract:
 
-1. Download mfsBSD ISO: https://depenguin.me/files/mfsbsd-15.0-RELEASE-amd64.iso
+1. install FreeBSD 15.x on the VPS,
-2. In Vultr panel: **Server → Settings → Custom ISO → Upload ISO**
+2. copy the Clawdie firstboot payload,
-3. Attach the ISO to your server
+3. boot into `clawdie-firstboot`,
-4. Reboot
+4. run `just install`,
+5. start the loopback-bound controlplane,
+6. rotate a one-time setup token,
+7. finish provider/model, Telegram, and operator account setup at `/setup`.
 
-### Step 2: Boot and SSH
+Provider keys and Telegram credentials are **not** install-time requirements.
-
+They can be pre-baked only for controlled images, but the preferred path is
-After reboot, the server boots into mfsBSD (FreeBSD in RAM):
+post-install setup.
-
-```bash
-ssh mfsbsd@<your-vps-ip>
-# password: mfsroot
-```
-
-### Step 3: Run Installer
-
-```bash
-fetch -o - https://clawdie.si/vps-setup.sh | sh
-```
-
-Or with custom config:
-
-```bash
-fetch -o setup.sh https://clawdie.si/vps-setup.sh
-# Edit ASSISTANT_NAME, AGENT_DOMAIN, TZ at the top
-vi setup.sh
-sh setup.sh
-```
-
-### Step 4: After Reboot
-
-```bash
-ssh clawdie@<your-vps-ip>
-cd ~/clawdie-ai
-just install
-```
-
-Done! Clawdie-AI is running on FreeBSD.
 
 ---
 
-## How It Works
+## Existing Files
 
+```text
+vps/
+├── setup.txt.tpl       # current preferred config template shape
+├── firstboot-vps.sh    # legacy/experimental headless firstboot entrypoint
+├── clawdie.conf.tpl    # deprecated compatibility template
+└── clawdie-vps-migrate.sh
 ```
-Vultr VPS
-  └─ Boot from mfsBSD ISO (FreeBSD in RAM)
-       └─ SSH as mfsbsd
-            └─ Run clawdie-vps-setup.sh
-                 ├─ Partition disk (ZFS)
-                 ├─ Install FreeBSD base
-                 ├─ Configure system (users, network, TZ)
-                 ├─ Install packages (node24, git, tmux, etc.)
-                 ├─ Download Clawdie-AI from Codeberg
-                 ├─ Generate secrets + .env
-                 └─ Reboot
 
-Final boot from HDD
+`setup.txt.tpl` now reflects the identity/substrate-first contract. The older
-  └─ FreeBSD + Clawdie-AI ready
+`clawdie.conf.tpl` path is deprecated.
-       └─ Run: just install
-```
 
 ---
 
-## Provider Support
+## Provider Notes
 
-| Provider | Method | Difficulty | Notes |
+| Provider         | Likely path                         | Status       |
-|----------|--------|------------|-------|
+| ---------------- | ----------------------------------- | ------------ |
-| **Vultr** | Custom ISO | Easy ⭐ | Upload mfsBSD ISO directly |
+| Vultr            | Custom ISO or mfsBSD rescue         | experimental |
-| **Hetzner** | Rescue + depenguin.me | Medium | Use depenguin.me script first |
+| Hetzner / OVH    | Rescue shell then FreeBSD bootstrap | experimental |
-| **OVH** | Rescue mode | Medium | Same as Hetzner |
+| DigitalOcean     | Recovery console / custom image     | hard         |
-| **Hostinger** | Check panel | Unknown | Look for ISO upload or rescue |
+| Generic baremetal| Unified ISO live installer          | primary      |
-| **DigitalOcean** | Recovery console | Hard | No ISO support, use depenguin.me |
-
----
-
-## Configuration Options
-
-Edit these at the top of `clawdie-vps-setup.sh`:
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `ASSISTANT_NAME` | Clawdie | Display name |
-| `AGENT_NAME` | clawdie | System hostname (auto-derived) |
-| `AGENT_DOMAIN` | clawdie.local | Domain name |
-| `TZ` | UTC | Timezone (e.g., Europe/Ljubljana) |
-| `PI_PROVIDER` | anthropic | LLM provider |
-| `CLAWDIE_VERSION` | 0.8.2 | Clawdie-AI release |
-
----
-
-## Files
-
-```
-clawdie-iso/vps/
-├── clawdie-vps-setup.sh     ← Main installer (runs on mfsBSD)
-├── clawdie-vps-migrate.sh   ← Linux→mfsBSD migration (for rescue mode)
-├── clawdie.conf.tpl         ← Headless config template
-└── firstboot-vps.sh         ← Alternative: interactive wizard
-```
 
 ---
 
 ## Security Notes
 
-1. **Change mfsBSD password** after first SSH if concerned
+- Prefer Tailscale for remote SSH access when possible.
-2. **All secrets auto-generated** with 32-char random strings
+- If no Tailscale auth key is available, SSH on port 22 remains public and must
-3. **.env mode 600** — only clawdie user can read
+  be secured by the operator.
-4. **Wheel group has passwordless sudo** — change if desired
+- Do not expose `http://127.0.0.1:3100/setup` directly to the public internet.
+  Use console access or SSH tunneling:
 
----
+```sh
-
+ssh -L 3100:127.0.0.1:3100 clawdie@<host>
-## Troubleshooting
-
-### SSH connection refused
-- Wait 30-60 seconds after reboot for mfsBSD to start
-- Check Vultr console for boot progress
-
-### Disk not detected
-- Check with: `sysctl kern.disks`
-- Manually set: `DISK=/dev/da0 ./clawdie-vps-setup.sh`
-
-### Install fails
-- Check internet: `fetch http://example.com`
-- Check logs in `/var/log/install.log`
-
----
-
-## Alternative: Build Custom ISO
-
-For fully offline installs, you can build a custom mfsBSD ISO with Clawdie pre-bundled:
-
-```bash
-cd clawdie-iso
-./build-vps.sh
-# Output: tmp/output/clawdie-vps-DD.mmm.YYYY.iso
 ```
 
-This requires more setup and is optional — the script approach above is simpler.
+---
+
+## Cleanup Needed Before Release
+
+- Reconcile `firstboot-vps.sh` with the current ISO live firstboot contract.
+- Remove the deprecated `clawdie.conf.tpl` path after migration is complete.
+- Add a real VPS validation run to `TESTING.md` once the path is exercised.
+
+**Last updated:** 12.maj.2026

firstboot/MODULE-MANIFEST.md

@@ -42,8 +42,8 @@
 **Wizard Inputs:** None
 
 **Outputs (Exports):**
-- `ASSISTANT_NAME`, `HOSTNAME`, `AGENT_DOMAIN`, `TZ`
+- identity/substrate values: `ASSISTANT_NAME`, `HOSTNAME`, `AGENT_DOMAIN`, `TZ`
-- `OPENROUTER_API_KEY`, `TELEGRAM_BOT_TOKEN`, `TELEGRAM_ADMIN_ID`
+- optional pre-baked provider/channel values, if present for backward compatibility
 - `ZFS_POOL`, `ZFS_LAYOUT`, `ZFS_DATA_DISKS`, `ZFS_HOT_SPARES`, `ZFS_PREFIX`
 - optional hardware hints from `system.env`
 
@@ -52,7 +52,7 @@
 **Skip Condition:**
 - no `CLAWDIE` FAT32 partition found
 - or `setup.txt` missing
-- or one of the three required bootstrap keys is blank
+- or identity/substrate values are incomplete for the non-interactive path
 
 **Error Handling:**
 - safe-fail back to wizard
@@ -89,13 +89,13 @@
 - `TZ` — Timezone (e.g., "Europe/Ljubljana")
 
 **Wizard Inputs (Tier 2 - Optional):**
-- `LLM_PROVIDER` — default: "anthropic"
+- Provider/model values — normally configured after first boot in `/setup`
-- `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc. — API keys (optional)
+- Provider API keys — optional backward-compatible pre-bake only
-- `TELEGRAM_BOT_TOKEN` — Telegram integration (optional)
+- Telegram credentials — optional backward-compatible pre-bake only
 
 **Outputs (Created):**
 - `$ENV_FILE` — `/home/clawdie/.env` (chmod 600)
-  - Contains: identity + feature flags from the firstboot wizard
+  - Contains: identity + feature flags from the live installer handoff or fallback wizard
 - Copied into: `/home/clawdie/clawdie-ai/.env` by shell-deploy (1.6)
   - Completed by: Clawdie-AI onboarding (secrets + derived defaults)
 
@@ -609,7 +609,7 @@ Use this manifest to:
 
 3. **Handle wizard tiers:**
    - Tier 1 (required): ASSISTANT_NAME, AGENT_DOMAIN, TZ
-   - Tier 2 (optional): LLM_PROVIDER, API keys, Telegram token
+   - Tier 2 (optional): provider/model and Telegram values for backward-compatible pre-bake
 
 4. **Define checkpoint names** for progress tracking
 
@@ -617,7 +617,7 @@ Use this manifest to:
 
 ## Version History
 
-- **v1.0.2** (current): 12 modules, ZFS/desktop/npm-globals, bundled npm CLIs
+- **current dev ISO**: live QML installer, post-install setup token, 12 shell modules, ZFS/desktop/npm-globals, bundled npm CLIs
 - **v0.9.0**: 8 modules, runtime GPU detection, no ZFS/desktop/npm-globals
 - **v0.5.0**: 6 modules, PF firewall, glasspane VNC support
 - **v1.1 (planned):** Add shell-gpu-passthrough.sh, add shell-upgrade.sh

firstboot/integration-test.sh

@@ -83,7 +83,7 @@ touch "$LOG_FILE" "$PROGRESS_FILE" "$RC_CONF" "$LOADER_CONF" "$SYSCTL_CONF"
 
 echo ""
 echo "╔════════════════════════════════════════════════════════════════╗"
-echo "║ Clawdie Shell v1.0.2 Integration Test                          ║"
+echo "║ Clawdie Shell Integration Test                                 ║"
 echo "║ 8-module sequential execution (cloud/VM scenario)              ║"
 echo "╚════════════════════════════════════════════════════════════════╝"
 echo ""
@@ -159,7 +159,7 @@ echo "║ System State:                                                  ║"
 [ -d "$CLAWDIE_AI_DIR" ] && echo "║   Clawdie-AI: deployed                                   ║" || echo "║   Clawdie-AI: MISSING                                  ║"
 
 echo "║                                                                ║"
-echo "║ GPU Support (v1.0.2):                                          ║"
+echo "║ GPU Support:                                                   ║"
 echo "║   ✓ Intel integrated (i915kms)                                 ║"
 echo "║   ✓ AMD AMDGPU                                                 ║"
 echo "║   ✓ VESA fallback                                              ║"

firstboot/shell-env.sh

@@ -100,11 +100,10 @@ clawdie_shell_env_append_new_keys() {
     fi
   }
 
-  # Keys added in v0.10.x / v1.0.0 that older installs may not have
+  # Keys added in v0.10.x / v1.0.0 that older installs may not have.
+  # Do not append provider/model defaults here; Clawdie-AI resolves those at
+  # runtime unless the operator explicitly configures them.
   _env_append_if_missing "DB_RUNTIME"         '"jail"'
-  _env_append_if_missing "EMBED_BASE_URL"     '"https://openrouter.ai/api/v1"'
-  _env_append_if_missing "EMBED_MODEL"        '"BAAI/bge-m3"'
-  _env_append_if_missing "EMBED_API_KEY"      '""'
   _env_append_if_missing "EMBED_DIMENSIONS"   '"1024"'
   _env_append_if_missing "LOCAL_LLM_PROVIDER" '"none"'
   _env_append_if_missing "FEATURE_OLLAMA"     '"NO"'
@@ -146,6 +145,29 @@ clawdie_shell_env_write_file() {
   cp_secret=$(openssl rand -base64 32)
   auth_secret=$(openssl rand -base64 32)
 
+  # Provider/model are intentionally unset by default; Clawdie-AI resolves the
+  # recommended runtime profile and post-install setup writes the operator's
+  # chosen provider. Embeddings follow the Clawdie-AI default: OpenRouter only
+  # when an OpenRouter key exists, otherwise local llama-server.
+  local pi_tui_provider pi_tui_model embed_base_url embed_model embed_api_key
+  pi_tui_provider="${PI_TUI_PROVIDER:-}"
+  pi_tui_model="${PI_TUI_MODEL:-}"
+  if [ -n "${EMBED_BASE_URL:-}" ]; then
+    embed_base_url="$EMBED_BASE_URL"
+  elif [ -n "${OPENROUTER_API_KEY:-}" ]; then
+    embed_base_url="https://openrouter.ai/api/v1"
+  else
+    embed_base_url="http://localhost:8080/v1"
+  fi
+  embed_model="${EMBED_MODEL:-BAAI/bge-m3}"
+  if [ -n "${EMBED_API_KEY:-}" ]; then
+    embed_api_key="$EMBED_API_KEY"
+  elif [ "$embed_base_url" = "https://openrouter.ai/api/v1" ]; then
+    embed_api_key="${OPENROUTER_API_KEY:-}"
+  else
+    embed_api_key=""
+  fi
+
   # Remove existing .env if present
   rm -f "$ENV_FILE" 2>/dev/null || true
 
@@ -174,8 +196,8 @@ SYSTEM_LOCALE="$SYSTEM_LOCALE"
 KEYMAP="$KEYMAP"
 
 # === LLM Provider ===
-PI_TUI_PROVIDER="${PI_TUI_PROVIDER:-zai}"
+PI_TUI_PROVIDER="$pi_tui_provider"
-PI_TUI_MODEL="${PI_TUI_MODEL:-glm-5}"
+PI_TUI_MODEL="$pi_tui_model"
 ZAI_API_KEY="${ZAI_API_KEY:-}"
 ZAI_API_BASE="${ZAI_API_BASE:-https://api.z.ai/api/coding/paas/v4}"
 OPENROUTER_API_KEY="${OPENROUTER_API_KEY:-}"
@@ -183,9 +205,9 @@ ANTHROPIC_API_KEY="${ANTHROPIC_API_KEY:-}"
 CLAUDE_CODE_OAUTH_TOKEN="${CLAUDE_CODE_OAUTH_TOKEN:-}"
 
 # === Embeddings ===
-EMBED_BASE_URL="${EMBED_BASE_URL:-https://openrouter.ai/api/v1}"
+EMBED_BASE_URL="$embed_base_url"
-EMBED_MODEL="${EMBED_MODEL:-BAAI/bge-m3}"
+EMBED_MODEL="$embed_model"
-EMBED_API_KEY="${EMBED_API_KEY:-}"
+EMBED_API_KEY="$embed_api_key"
 EMBED_DIMENSIONS="${EMBED_DIMENSIONS:-1024}"
 
 # === Database ===

vps/setup.txt.tpl

@@ -1,14 +1,13 @@
 # setup.txt — Headless VPS installation config
 # Copy to /usr/local/share/clawdie-iso/setup.txt before running firstboot-vps.sh
 #
-# This is the same first-boot setup contract used by the USB installer.
+# Provider keys and Telegram are no longer required at install time. Configure
-
+# them after first boot through the Clawdie setup page unless you deliberately
-OPENROUTER_API_KEY=
+# want to pre-bake credentials for a controlled image.
-TELEGRAM_BOT_TOKEN=
-TELEGRAM_ADMIN_ID=
 
 ASSISTANT_NAME=Clawdie
 HOSTNAME=clawdie
+AGENT_DOMAIN=clawdie.home.arpa
 TIMEZONE=UTC
 INSTALL_MODE=fresh
 
@@ -18,7 +17,18 @@ ZFS_DATA_DISKS=1
 ZFS_HOT_SPARES=0
 ZFS_PREFIX=clawdie-runtime
 
-# Optional
+# Optional access
+# SSH_AUTHORIZED_KEY=ssh-ed25519 AAAA...
+# CLAWDIE_USER_PASSWORD=
+
+# Optional pre-baked provider/channel credentials (prefer post-install /setup)
+# OPENROUTER_API_KEY=
+# OPENAI_API_KEY=
+# ANTHROPIC_API_KEY=
+# ZAI_API_KEY=
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_ADMIN_ID=
+
+# Optional locale
 # SYSTEM_LOCALE=en_US.UTF-8
 # KEYMAP=us
-# SSH_AUTHORIZED_KEY=ssh-ed25519 AAAA...