Codifies the markdown format Sam applied in bd94b87 / 30cf590 as a
project rule rather than per-file judgment. Prettier 3 defaults with
proseWrap=preserve (no prose reflow), printWidth=80, embedded code
formatting off so we don't touch fenced shell/JSON blocks.
.prettierignore scopes Prettier to active docs:
- excludes tmp/, cache/, node_modules/, build artifacts
- excludes CHANGELOG.md + RELEASE-NOTES-*.md (hand-formatted, rigid)
- excludes .archive/ and .opencode/ (historical / tooling internal)
- excludes bundled bootstrap.html
Reformatted 16 active .md files: padded markdown tables, blank line
before lists (CommonMark-strict), `*emph*` -> `_emph_`. No content
changes — diffs are all whitespace/alignment/emphasis style.
Verified: `npx prettier@3 --check '**/*.md'` reports all clean.
Build: not run — docs + tooling config only.
Tests: pass — prettier --check is green; git diff confirms no content
deletions, only formatting.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Install and verify the live operator bash profile path so SSH, TTY, terminal, and su login sessions see the npm global pi tooling. Prefer /usr/local/bin/bash for the live and installed clawdie user while retaining /bin/sh fallback during partial firstboot recovery.
No image build run.
---
Build: pass — sh -n build.sh; sh -n firstboot/shell-ssh.sh; sh -n firstboot/shell-system.sh
Tests: pass — git diff --check
Small follow-up after 9e64a82's Firefox + deferred-bundle work landed.
Trims wavering language from docs and historical-banners the QML phase 4
doc to match the pattern used elsewhere.
Changes:
- BUILD.md
Audit-candidates row for `bitchx`: drop the "Probably belongs in
the disk-install bundle above; verify before next build" line.
bitchx stays on the live USB; size impact is negligible and the
operator may want a quick chat tool on a fresh boot.
- doc/LIVE-SESSION-REVIEW.md
Remove the L7 "Firefox IS in package list — L5 concern mitigated"
block. Both the cross-ref to L5 (unrelated to browser packages)
and the finding itself were redundant noise once the Firefox swap
landed.
Past-tense the audio expectation: "After the bundle move +
Chromium→Firefox swap (both landed in 9e64a82)..." replaces the
forward-looking phrasing.
Minor: fix broken-line sentence in the Post-84358ac review header.
- TESTING.md
Drop "not the older Lumina-first installer flow" — Lumina is fully
archived; the comparison is no longer informative.
- firstboot/gui/PHASE4-INTEGRATION-COMPLETE.md
Add a historical banner matching the pattern used on
ROADMAP-v1.0.0.md and docs/PHASE4-TEST-REPORT-06.APR.2026.md. The
doc still accurately describes the abandoned Qt6/QML installer
under firstboot/gui/qml-installer/; the banner makes that clear.
Not touched (verified accurate or intentional):
- BUILD.md "Provider keys, Telegram, and disk deployment are deferred
on this branch" — accurate present state.
- README.md "later phases" / "intentionally deferred" wording — accurate.
- FIRSTBOOT.md "deferred to runtime" in shell-deploy error handling —
accurate.
- ROADMAP-v1.0.0.md, RELEASE-NOTES-v0.9.0.md, docs/PHASE4-TEST-REPORT-*
— already banner-marked as historical.
- BUILD.md's two remaining Chromium references — both explain *why*
Firefox was chosen (the chain it avoids). Useful context, kept.
Build: pass — sh -n build.sh
Tests: pass — git diff --check
Top-level doc count: 24 → 13. No plans or technical content removed —
this commit is pure consolidation and archival.
Merge (3 → 1):
SHELL-ARCHITECTURE.md (665 lines)
SHELL-MODULES.md (769 lines)
firstboot/MODULE-MANIFEST.md (628 lines)
→ FIRSTBOOT.md (710 lines)
The three deleted files described the same firstboot/ codebase from three
angles (philosophy, function reference, dependency graph). A reader trying
to understand a module had to cross-reference all three; FIRSTBOOT.md
unifies them as one doc with sections (philosophy, architecture, dependency
graph, per-module reference, error handling, testing, POSIX rules).
Archive (8 docs → .archive/completed-work/):
CLAWDIE-ISO.md (self-flagged DEPRECATED)
QT6-IMPLEMENTATION-PLAN.md (Qt6 installer direction abandoned)
PHASE4-SUMMARY.md (phase complete)
PHASE4-TESTING-INSTRUCTIONS.md (phase complete)
INSTALLER-PLAN.md (Apr 2026 plan, predates xfce-operator-usb)
doc/ISO-LIVE-GUI-SETUP-PROPOSAL.md (proposal; design now in code)
doc/NOMADBSD-XFCE-USB-POC.md (POC findings; SDDM+XFCE design now in code)
doc/OPERATOR-USB-XFCE-PROPOSAL.md (proposal → reality)
Link updates in active docs:
README.md two links replaced by FIRSTBOOT.md reference
TESTING.md two links replaced by FIRSTBOOT.md reference
doc/SESSION-STAB-HANDOFF.md CLAWDIE-ISO.md reference re-pathed to
.archive/completed-work/
Left intentionally untouched:
CHANGELOG.md historical v0.9.0 entry naming SHELL-MODULES.md —
release notes are version-frozen
RELEASE-NOTES-v0.9.0.md same reason
End state:
Top-level docs: 24 → 13
Visible KB: ~290 → ~170
Plans preserved: 100% (8 archived, 3 merged)
Build: pass — sh -n build.sh
Tests: pass — git diff --check
Remove unused Lumina/live-installer package lists, keep SDDM on an interactive-greeter path with the Clawdie XFCE session preselected, and clean active docs that still described the superseded Lumina or autologin plans.
---
Build: pass — sh -n build.sh
Tests: pass — git diff --check
The xfce-operator-usb live USB has been failing with the documented
FreeBSD-specific LightDM+XFCE login-loop bug: ConsoleKit session
activation fails on FreeBSD, X session exits rc=1, LightDM restarts
the greeter, loop. The FreeBSD forum thread tracking this exact symptom
remains unresolved upstream as of January 2026.
NomadBSD — the FreeBSD live-USB spin we already borrow ideas from —
switched from SLiM to SDDM for the same class of reasons. SDDM does
not depend on ConsoleKit the same way LightDM does, and its QtQuick
greeter shares a toolkit with the QML installer we already maintain.
This commit:
- Drops lightdm/lightdm-gtk-greeter, adds sddm in pkg-list-xfce.
- Replaces live/operator-session/lightdm-live.conf with
live/operator-session/sddm.conf, installed to
/usr/local/etc/sddm.conf.d/50-clawdie-live.conf.
- Drops autologin by default. The live USB now boots to the SDDM
greeter; the operator logs in as clawdie with the documented live
password (quindecim when built with --live-default-password).
Autologin can be re-enabled per machine by setting User= and
Session= under [Autologin] in the installed sddm.conf.d file.
- Flips rc.conf to sddm_enable / display_manager=sddm in build.sh,
firstboot/shell-system.sh, and firstboot/shell-desktop.sh.
- Updates the clawdie_live_gpu rc.d ordering directive from
BEFORE: lightdm to BEFORE: sddm so the GPU detector still runs
before the display manager.
- Removes the LightDM placeholder-config workaround in build.sh
(SDDM has no equivalent pkg-script requirement).
- Removes the unused live/installer-session/lightdm-live.conf
(build.sh hasn't referenced it since the move to XFCE).
- Sweeps LightDM references in README, BUILD, TESTING, SHELL-MODULES,
SHELL-ARCHITECTURE, and MODULE-MANIFEST. Leaves historical
validation findings in doc/NOMADBSD-XFCE-USB-POC.md alone (those
document prior LightDM-era inspections and should remain accurate
for that point in time).
Build: pass — sh -n build.sh, sh -n firstboot/shell-system.sh,
sh -n firstboot/shell-desktop.sh
Tests: pass — git diff --check
Refresh build, testing, requirements, and historical design docs for the current XFCE operator USB path, including pre-LightDM GPU detection, mdo-based operator actions, and the published quindecim workflow.
---
Build: pass — sh -n build.sh
Tests: pass — git diff --check
Keep the first rebuild explicit with mdo-based Bastille use, fix rc.conf list appends, and clean new ISO skill EOF whitespace.
---
Build: pass — sh -n build.sh; sh -n firstboot/shell-system.sh
Tests: pass — git diff --check
Include xfce4-mixer in the active XFCE package list, align the proposal with the fixed clawdie USB user and post-boot Tailscale authentication flow, and remove seatd from the firstboot LightDM/X11 service path.
---
Build: pass — ./build.sh completed without --skip-fetch
Tests: pass — mounted-image static inspection confirmed xfce4-mixer installed and no seatd_enable in rc.conf; runtime boot unavailable on nested KVM host
- TESTING.md: expected output banner now matches updated integration-test.sh
- shell-env.sh: EMBED_BASE_URL defaults to empty when no OpenRouter key exists, letting config.ts resolve dynamically at runtime instead of baking localhost:8080 into .env
- shell-pf.sh: BRIDGE is now always warden0 (matches jail-config.ts and AGENTS.md)
- CompletePage.qml: token text now says will be generated after first boot
- NETWORKING.md: updated to reflect warden0 fix
Collect optional SSH public key and Tailscale auth key in the live installer, keep the controlplane loopback-bound by default, allow SSH over tailscale0, and rotate the post-install setup token into /var/db/clawdie-installer/setup-token with MOTD guidance for SSH tunnel access.
This slice is install-mode only; upgrade runs do not mint a new setup token.
Build: pass
Tests: pass — sh -n + QML build + config-format + mocked setup-token writer dry-run
Real-disk / bhyve install: NOT YET TESTED
Live GUI installs now write runtime handoff files under /var/run/clawdie-installer, invoke bsdinstall script through a dedicated commit helper, persist the installed handoff for first HDD boot, and point the operator at /setup after reboot.
The live autologin user is restricted to a narrow sudoers rule for the commit helper and reboot only.
Build: pass
Tests: pass — sh -n + QML build + config-format + stubbed live-commit dry-run
Real-disk / bhyve install: NOT YET TESTED
Generate CONTROLPLANE_SHARED_SECRET and BETTER_AUTH_SECRET at install
time via openssl rand. Add CONTROLPLANE_HOST_IP, CONTROLPLANE_AUTH_MODE,
CONTROLPLANE_PORT, BETTER_AUTH_URL, GIT_LOCAL_URL to both install heredoc
and upgrade append path. Default to bare git repo (CODE_HOSTING_MODE=git)
instead of Forgejo.
---
Build: pass | Tests: not run (Linux) — shell script, bash -n validated
Four critical fixes before v1.0.0 VM test, informed by PC-BSD failure
modes and GhostBSD's improvements:
1. shell-zfs.sh: zpool labelclear on fresh install
Clear ZFS labels from every device that was in the old pool before
bsdinstall writes new ones. Prevents the "can't find pool by GUID"
boot failure that made PC-BSD reinstalls unreliable.
2. shell-zfs.sh: pre-upgrade snapshot
When operator selects Upgrade, take zfs snapshot -r
pool@pre-upgrade-{timestamp} before any changes. One reboot to
roll back if the upgrade goes wrong. UPGRADE_SNAPSHOT exported for
downstream modules to reference.
3. shell-env.sh: never overwrite secrets on upgrade
clawdie_shell_env_generate() now checks CLAWDIE_BOOT_MODE. In
upgrade mode it calls clawdie_shell_env_append_new_keys() instead
of regenerating — reads existing .env and appends only keys that
are absent. Existing DB passwords, JWT secrets, API keys are never
touched. This fixes the root cause of the orphaned-database bug:
new passwords that don't match the existing pool's data.
4. firstboot.sh: module execution matrix via run_step_if
New run_step_if "<modes>" wrapper marks steps as done without
running them when not applicable to the current boot mode.
Upgrade skips: gpu, nvidia, ssh, system, desktop, pf, tailscale
Upgrade runs: pkg, env (append-only), npm-globals, deploy
Prevents SSH key resets, rc.conf overwrites, and firewall rewrites
during upgrade — all of which undid operator customisations.
Also adds INSTALLER-PLAN.md: full architecture plan for unified
GUI/TUI installer with Fresh / Upgrade / Repair modes, boot
environment support, and a clear phase roadmap to v1.1.0.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
shell-deploy.sh was dropping to the clawdie user before running
just install. setup/service.ts checks isRoot() to decide whether
to install the rc.d service or generate start/stop wrappers — so
running as clawdie meant the agent was never registered with
FreeBSD's service manager and never started at boot.
Fix: run the installer as root. setup/service.ts already handles
privilege separation correctly when invoked as root: it writes
/usr/local/etc/rc.d/{agent}, adds -u {agent} to daemon args so
the running process is never root, and chowns data/logs/groups to
the agent user to prevent EACCES on first write.
Also adds DB_RUNTIME to the generated .env seed so operators can
see the jail vs host postgres option without reading the docs.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
- build.sh now runs npm ci at ISO build time and bundles node_modules into the clawdie-ai payload tarball\n- firstboot deploy ensures node_modules exist (fallback: npm ci, network required)\n- test mode skips venv/model seeding + verify to avoid host side effects\n- docs/tests updated to match
ISO deploy module now runs `just install` (with a dev fallback to `npm run install`) instead of `npm run install-all`, and docs/tests are updated accordingly.
- Updated firstboot completion messages: Aider and Pi now listed as primary harnesses, Codex as optional
- Added [Unreleased] section to CHANGELOG documenting Aider venv provisioning and harness integration
- Reflects completion of Aider+Pi harness migration across clawdie-ai and clawdie-iso
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
Add py311-aider_chat to host baseline for the controlplane harness
(Aider + Pi multi-agent orchestrator). Add forgejo package to jail
list for the code service. Bake ZAI_API_BASE into firstboot .env
to fix litellm endpoint mismatch discovered during Aider testing.
---
Build: pass | Tests: not run (Linux)
Ships @anthropic-ai/claude-code, @google/gemini-cli, and
@mariozechner/pi-coding-agent as prebuilt .tgz tarballs on the install
media so the agent runtime has its CLI dependencies on first boot
without network access.
Critical: installs to /home/clawdie/.npm-global to match the
npm_config_prefix set by shell-system.sh in /etc/profile.d/clawdie.sh,
so the clawdie user's PATH (and the agent's commandExists() probes)
actually resolve the binaries.
- scripts/fetch-npm-globals.sh: npm pack the 3 CLIs into tmp/npm-globals/
- firstboot/shell-npm-globals.sh: offline install as clawdie user with
matching prefix, runs between pkg setup and deploy
- build.sh: fetch + bundle into ${SHARE}/npm-globals/
- firstboot.sh: source module and run_step before deploy
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Add ANTHROPIC_API_KEY and CLAUDE_CODE_OAUTH_TOKEN as optional password
fields to both shell wizard and GUI installer. Fields flow through to
.env via shell-env.sh. Document /tmp exemption in AGENTS.md.
Fix 2 critical issues preventing Phase 4 from working on FreeBSD:
1. Path Detection (main.cpp:438-447)
- Detect firstboot.sh location at runtime
- Try /usr/local/share/clawdie-iso/firstboot/firstboot.sh (live ISO)
- Fall back to /home/clawdie/clawdie-iso/firstboot/firstboot.sh (dev)
- Error with helpful message if neither found
- Closes blocker: installer now works on both dev + ISO
2. Progress Tracking (firstboot.sh:49-65, 253-262)
- Add optional _step_num parameter to run_step() function
- Write PROGRESS=N to progress file after each step completes
- Update all 10 step calls with step numbers (1-8)
- Closes blocker: progress bar now moves from 0% to 100%
3. Privilege Escalation (main.cpp:460)
- Add sudo wrapper to firstboot.sh execution
- Prompts for password when needed
- Closes blocker: pkg/sysrc operations now succeed
Files changed:
- main.cpp: +13 lines (path detection + sudo)
- firstboot.sh: +7 lines (progress tracking)
All changes validate:
- C++ compiles clean (2 pre-existing warnings)
- Shell syntax valid (sh -n)
- Binary created: 115 KB
Status: Ready for ISO build + FreeBSD testing
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
