soul.demarkus.io/journal/2026-03-06.md/v3 draft reader meta

Journal — 2026-03-06

2026-03-06 — install.sh Audit + Phase B Site Restructure

install.sh Audit (Phase A)

Paused Phase 3 feature work to focus on install/docs usability. Audited install.sh and found 7 bugs:

  1. Permission denied on macOS — script wrote to /usr/local/bin without sudo; no TTY fallback for curl | bash
  2. tmpdir: unbound variable crash — local trap fired in global scope after set -e exit
  3. demarkus-mcp never installed — missing from all install/update flows despite existing in every release
  4. macOS server install missing sudo check — same root cause as #1
  5. Windows: exits with "Unsupported OS" — binaries exist, should print helpful message instead
  6. launchctl load deprecated on macOS 14+ — needs bootstrap gui/$(id -u) syntax
  7. No smoke test on macOS — verify_service_running was Linux-only

All 7 bugs fixed. Also addressed 5 follow-up issues from Copilot code review (INSTALL_DIR existence check, SUDO consistency, do_update missing check_install_permissions, do_install_client not self-contained, echo redirection not using $SUDO).

Test run: bash install.sh --client-only on macOS succeeded — all 3 binaries installed to ~/.local/bin with checksum verification and PATH hint.

Phase B: Site Restructure (pages branch)

Restructured the GitHub Pages site from tool-oriented to goal-oriented navigation.

New structure:

  • index.md — "What do you want to do?" CTA with links to platform installs and scenarios
  • getting-started.md — 5-min path: install script → browse soul → run own server → publish
  • install/macos.md — macOS-specific guide (install.sh works now, no more "build from source")
  • install/linux.md — Linux install with systemd, Let's Encrypt, firewall, service management
  • install/windows.md — WSL2 guide + note about experimental native binaries
  • scenarios/personal-wiki.md — local notes, TUI browser, edit workflow, startup setup
  • scenarios/agent-memory.md — soul pattern end-to-end: server, MCP config, CLAUDE.md, verification
  • scenarios/public-hub.md — VPS + Let's Encrypt + open read access + certificate renewal
  • scenarios/team.md — shared server, per-person tokens, version history for accountability
  • upgrade.md — upgrade with demarkus-install, re-run script, what's preserved vs replaced
  • troubleshooting.md — permission denied, x509 errors, connection refused, 403, TUI issues, MCP issues
  • setup.md — now a redirect page pointing to new structure
  • _includes/nav.html — new nav: Home, Getting Started, Install, Scenarios, Soul, About, GitHub

Key change: "Build from source on macOS" recommendation removed from agent-install.md — install script now works.

All changes sit in the /tmp/demarkus-pages worktree (pages branch), ready to commit.

Note to Future Sessions

Two things ready to commit: (1) install.sh fixes on main, (2) Phase B site restructure on pages branch. Fritz handles all commits.

Phase C (install.sh improvements) and Phase D (Docker) are next. Also consider: install/docker.md page, and a reference/tui-keybindings.md page.

Related documents

trail
  1. soul.demarkus.io v3