clawdie-iso/firstboot/MODULE-MANIFEST.md

Clawdie Shell Module Manifest

Purpose: Explicit dependency graph for 6-module pipeline (Phase 1) Used by: firstboot.sh wizard (Phase 2.1) for sequencing and recovery

---

Module Dependencies Map

[User Input]
    ↓
[1.1 env] → ASSISTANT_NAME, AGENT_DOMAIN, TZ, LLM_PROVIDER
    ↓
    ├→ [1.2 pkg] (optional: can run any time)
    ├→ [1.3 gpu] (optional: hardware detection)
    ├→ [1.3b nvidia] ← REQUIRES: DETECTED_GPU from [1.3]
    ├→ [1.4 system] ← REQUIRES: TZ, AGENT_DOMAIN from [1.1]
    └→ [1.5 deploy] ← REQUIRES: .env from [1.1]
                      ← REQUIRES: repos from [1.2]
                      ← PREFERS: gpu config from [1.3]

---

Module Specifications

1.1: clawdie-shell-env.sh

Purpose: Generate .env with 65+ environment variables (identity + structural)

Wizard Inputs (Tier 1 - Required):

• ASSISTANT_NAME — Human name (e.g., "Clawdie Smith")
• AGENT_DOMAIN — FQDN (e.g., "clawdie.local")
• TZ — Timezone (e.g., "Europe/Ljubljana")

Wizard Inputs (Tier 2 - Optional):

• LLM_PROVIDER — default: "anthropic"
• ANTHROPIC_API_KEY, OPENAI_API_KEY, etc. — API keys (optional)
• TELEGRAM_BOT_TOKEN — Telegram integration (optional)

Outputs (Created):

• $ENV_FILE — /home/clawdie/clawdie-ai/.env (chmod 600)
  • Contains: ASSISTANT_NAME, AGENT_NAME, AGENT_DOMAIN, TZ, all 65 vars
  • Sourced by: clawdie-shell-deploy (1.5)
  • Sourced by: clawdie-shell-system (1.4) implicitly

Exports (for downstream modules):

• AGENT_NAME — derived from ASSISTANT_NAME (e.g., "clawdie-smith")
• DETECTED_ABI — optional (from pkg config abi)

Checkpoint Name: [ENV]

Skip Condition:

• If .env exists AND contains AGENT_DOMAIN: skip (idempotent)

Error Handling:

• Fails if ASSISTANT_NAME, AGENT_DOMAIN, or TZ missing
• Creates /home/clawdie/clawdie-ai directory if needed
• Validates .env has 50+ variables before marking complete

Recovery Note:

• If 1.1 fails, user runs clawdie-firstboot --resume
• Skips 1.1 if [ENV] COMPLETE in progress file
• Can re-run to update .env (idempotent via sysrc pattern)

---

1.2: clawdie-shell-pkg.sh

Purpose: Configure package repositories (online FreeBSD + offline USB)

Wizard Inputs: None (automatic from [1.1])

Inputs from [1.1]:

• DETECTED_ABI — optional (auto-detected if missing)
  • Used for FreeBSD repo URL: pkg+https://pkg.FreeBSD.org/${ABI}/latest

Outputs (Created):

• /etc/pkg/repos/FreeBSD.conf

  • Online repo, priority 10 (fallback)
  • URL: pkg+https://pkg.FreeBSD.org/FreeBSD:15:amd64/latest
  • Enable: yes

• /etc/pkg/repos/Clawdie-USB.conf

  • Offline USB repo, priority 100 (preferred)
  • URL: file:///mnt/media/packages
  • Enable: yes

• /var/cache/pkg/bastille/

  • Seeded with .pkg files from USB (for offline jail provisioning)

Exports: None

Checkpoint Name: [PKG]

Skip Condition:

• If both FreeBSD.conf AND Clawdie-USB.conf exist: skip

Error Handling:

• Safe to fail: If USB packages missing, continues (online only)
• pkg update may fail in chroot (expected, logged as warning)
• Cache seeding errors are non-fatal (safe-fail with || true)

Recovery Note:

• Can re-run to update repo configs
• If jails fail to provision, user may re-run 1.2 to refresh cache
• Dependency-free: can run before or after 1.1 (but run 1.1 first for ABI)

---

1.3: clawdie-shell-gpu.sh

Purpose: Detect GPU hardware, select driver kernel module

Wizard Inputs: None (automatic detection)

Inputs from [1.1]:

• None (hardware detection is autonomous)

Hardware Detection (via pciconf -lv):

• Intel → i915kms
• AMD → amdgpu
• NVIDIA → nvidia (sets DETECTED_GPU="nvidia")
• VMware → vmwgfx
• Unknown → vesa (fallback)

Outputs (Created):

• /etc/rc.conf (append/update):
  • kld_list="i915kms" (or amdgpu, vesa, etc.)
  • Idempotent: updates if already exists

Exports (for downstream):

• DETECTED_GPU — "intel", "amd", "nvidia", "vmware", or "vesa"
  • Used by [1.3b nvidia] to decide: run or skip

Checkpoint Name: [GPU]

Skip Condition:

• If kld_list= already in rc.conf: skip

Error Handling:

• pciconf may fail outside chroot (expected)
• Silently falls back to "vesa" if detection fails
• kldload live fails gracefully (expected in chroot)

Recovery Note:

• Can re-run to re-detect GPU
• No dependencies on [1.1], [1.2]
• MUST run before [1.4 system] (which reads rc.conf)
• REQUIRED before [1.3b nvidia]

---

1.3b: clawdie-shell-nvidia.sh ⭐ (NEW in Option B)

Purpose: NVIDIA driver version selection (PC-BSD heritage)

Wizard Inputs (optional, Tier 2):

• NVIDIA_DRIVER_VERSION — "590", "470", or "390" (env var for unattended)
• OR: interactive bsddialog menu if not set

Inputs from [1.3 gpu]:

• ✅ REQUIRED: DETECTED_GPU variable
  • If DETECTED_GPU ≠ "nvidia": skip gracefully
  • If DETECTED_GPU = "nvidia": show driver selection

Outputs (Created):

• /etc/rc.conf (append/update):

  • nvidia_driver_version="590" (or "470", "390")
  • Idempotent: updates if exists

• /var/run/nvidia_driver_version.txt (optional, safe-fail):

  • Marker file for build system
  • Non-critical; failure is ignored

Exports (for downstream):

• NVIDIA_DRIVER_VERSION — "590", "470", or "390"
  • Used during package selection in 1.5

Checkpoint Name: [NVIDIA]

Skip Condition:

• If DETECTED_GPU ≠ "nvidia": skip (returns 0 without error)
• If nvidia_driver_version= already in rc.conf: skip

Driver Mapping:

• 590 → nvidia-driver-590 (Maxwell & newer: GTX 750 Ti+, RTX 20/30/40)
• 470 → nvidia-driver-470 (Kepler: GTX 600/700, Titan Black)
• 390 → nvidia-driver-390 (Fermi: GTX 400/500)

Error Handling:

• Invalid version: logs warning, uses default "590"
• bsddialog not available: silently uses default
• /var/run write fails: non-fatal, continues

Recovery Note:

• DEPENDS ON [1.3 gpu]: WILL FAIL if DETECTED_GPU not set
• Can run after [1.3], before [1.4], [1.5]
• Unattended mode: set NVIDIA_DRIVER_VERSION env var before wizard

---

1.4: clawdie-shell-system.sh

Purpose: System configuration (hostname, timezone, rc.conf, services)

Wizard Inputs (from [1.1]):

• TZ — Timezone (e.g., "Europe/Ljubljana")
• AGENT_DOMAIN — FQDN (e.g., "clawdie.local")

Inputs from [1.3 gpu]:

• rc.conf already updated by [1.3] (this module appends to it)

Outputs (Created/Modified):

• /etc/rc.conf (append/update):

  • timezone="Europe/Ljubljana"
  • dbus_enable="YES"
  • hald_enable="YES"
  • seatd_enable="YES"
  • display_manager="lightdm"
  • lightdm_enable="YES"
  • Idempotent: uses sysrc pattern

• /etc/hostname:

  • Contains single line: clawdie.local

• /etc/profile.d/clawdie.sh:

  • npm environment (PATH, npm_config_prefix)

Exports: None

Checkpoint Name: [SYSTEM]

Skip Condition:

• If timezone= AND dbus_enable= already in rc.conf: skip

Error Handling:

• hostname command may fail in chroot (safe-fail)
• service onestart fails gracefully (expected in chroot)
• Missing /etc/profile.d: creates directory

Recovery Note:

• DEPENDS ON [1.1]: requires TZ, AGENT_DOMAIN
• Can run after [1.3], before [1.5]
• Idempotent: safe to re-run

---

1.5: clawdie-shell-deploy.sh

Purpose: Extract Clawdie-AI, npm install, create jails, start services

Wizard Inputs: None (automatic)

Inputs from [1.1] — REQUIRED:

• .env file must exist (path: $ENV_FILE)
  • Sourced to get: ASSISTANT_NAME, AGENT_DOMAIN, jail IPs, DB config
  • Failure if missing: hard exit

Inputs from [1.2] — PREFERRED (not required):

• Repos configured (speeds up offline provisioning)
• Pkg cache seeded (enables offline jail setup)
• But: can run without [1.2] (falls back to online)

Inputs from [1.3], [1.3b] — OPTIONAL:**

• rc.conf kld_list (already applied to system)
• nvidia_driver_version (used for jail package selection)

Outputs (Created):

• /home/clawdie/clawdie-ai/.env — sourced from [1.1]
• Clawdie-AI directory structure extracted
• node_modules/ installed (npm install)
• Jails created (worker, db, cms, optional mgmt)
• Services provisioned (npm run install-all)

Exports: None

Checkpoint Name: [DEPLOY]

Skip Condition:

• If Clawdie-AI/package.json AND node_modules/ exist: skip extraction + npm install
• But: always runs npm run install-all (jails may need provisioning)

Error Handling:

• Missing .env: hard exit (module exits with error)
• Missing tarball: logs warning, assumes already extracted
• npm install failures: logs warning, continues
• Jail creation failures: logs warning, continues
• DB connectivity failures: deferred to runtime

Recovery Note:

• HARD DEPENDENCY ON [1.1]: will fail if .env missing
• Should run AFTER [1.1], [1.2], [1.3], [1.4]
• Can be re-run for idempotency (skips if already deployed)
• Failures here block full system setup

---

Execution Order (from Integration Test)

User Input (wizard Tier 1 + optional Tier 2)
    ↓
1.1 env ✓ REQUIRED (creates .env with identity)
    ↓
1.2 pkg ✓ OPTIONAL (but run early for offline support)
    ↓
1.3 gpu ✓ RECOMMENDED (hardware detection)
    ↓
1.3b nvidia ✓ CONDITIONAL (only if GPU=nvidia)
    ↓
1.4 system ✓ REQUIRED (system-level config)
    ↓
1.5 deploy ✓ REQUIRED (depends on .env from 1.1)
    ↓
SUCCESS: Clawdie-AI ready for first boot

---

Resume/Recovery Rules (for Phase 2.1)

Rule 1: Hard Dependencies

• 1.1 must complete before 1.5 (1.5 sources .env)
• 1.3 must complete before 1.3b (1.3b checks DETECTED_GPU)
• 1.4 should run before 1.5 (system config affects jails)

Rule 2: Skip Logic on Resume

# Pseudo-code for firstboot.sh --resume logic:

if grep -q "[ENV] COMPLETE" $PROGRESS_FILE; then
  skip_module env
fi

if grep -q "[PKG] COMPLETE" $PROGRESS_FILE; then
  skip_module pkg
fi

if grep -q "[GPU] COMPLETE" $PROGRESS_FILE; then
  skip_module gpu
fi

if grep -q "[NVIDIA] COMPLETE" OR DETECTED_GPU != "nvidia"; then
  skip_module nvidia
fi

# ... etc

Rule 3: Error Recovery

• Soft failure (warning): Module logs error but continues

  • Examples: gpu live-load fails, pkg update fails
  • Action on resume: re-run module (idempotent)

• Hard failure (exit 1): Module exits shell

  • Examples: .env missing in 1.5, AGENT_DOMAIN not set
  • Action on resume: fix input, re-run from beginning

---

For Phase 2.1 Implementation

Use this manifest to:

1. Sequence modules in firstboot.sh:

   . clawdie-shell-env.sh
   clawdie_shell_env_generate  # [ENV] COMPLETE
   
   . clawdie-shell-pkg.sh
   clawdie_shell_pkg_setup  # [PKG] COMPLETE
   
   # ... etc
   

2. Implement resume logic:

   # If --resume, skip completed modules
   grep -q "[ENV] COMPLETE" $PROGRESS && skip_env=1
   

3. Handle wizard tiers:

   • Tier 1 (required): ASSISTANT_NAME, AGENT_DOMAIN, TZ
   • Tier 2 (optional): LLM_PROVIDER, API keys, Telegram token

4. Define checkpoint names for progress tracking

---

Version History

• v0.9.0 (current): 6 modules, cloud/VM GPUs, no passthrough
• v1.0 (planned): Add clawdie-shell-gpu-passthrough.sh, add clawdie-shell-upgrade.sh