Golem Setup Wizard

First-time setup for the golems ecosystem on a new Mac. Checks deps, wires MCPs, symlinks skills. Also the role-aware fresh-machine wizard (formerly wizard) and the installed-skill lister (formerly skills).

Fresh-machine wizard

CARDINAL RULE: all opt-in features are OFF by default. The user explicitly enables each one.

Full procedure: references/wizard.md; phase checklist: workflows/wizard-setup.md. Preflight: bash <golem-install-dir>/scripts/wizard-preflight.sh.

1. Prerequisites: brew node bun claude gh git, all 6 required; then gh auth status. Run bash <golem-install-dir>/scripts/install-python.sh to provision the golems-owned ~/.golems/venv with hash-pinned PyYAML before MCP config sync.
2. Config: read or create ~/.golems/config.yaml. machineRole is workspace or daemon-host, asked, never inferred; the workspace root must exist.
3. Artifacts and repos: bun <golem-install-dir>/scripts/repo-action.mjs "$MACHINE_ROLE" reads release-gate.json (the only classification): INSTALL never clones, CLONE only for kind:"none" on a workspace, REFUSE clones nothing. Then bun <golem-install-dir>/scripts/install-codex-config.mjs --source-dir <source>/config/codex renders the implementation/internal-mechanical roles into the two model keys, preserving all non-model settings. Then bun <golem-install-dir>/scripts/install-cmuxlayer-fleet.mjs writes cmuxlayer's ~/.config/cmuxlayer/fleet.json (golems coordination/outbox/launcher paths) only if absent; add --with-worktree-bootstrap only once the installed cmuxlayer supports that key (after #857).
4. MCP: golems/scripts/sync/sync-config.sh --diff, confirm, then --enforce.
5. .claude.local.md in each existing checkout that has a CLAUDE.md (gitignored). A machine whose skill links point at a stale ~/.golems/skills copy: bun <golem-install-dir>/scripts/repoint-skills.mjs --source <clone>/skills/golem-powers (dry-run; --apply repoints and drops dangling links, per-root counts for ~/.claude/skills, ~/.agents/skills, ~/.codex/skills, ~/.gemini/config/skills; a missing root is skipped). Gemini sees only a few skills: add --link-missing to create ~/.gemini/config/skills/<name> → ../../../.agents/skills/<name> for each golems skill linked in ~/.agents/skills but absent there (never overwrites; skipped without ~/.gemini/config; dry-run unless --apply; reports linked=N). The Gemini CLI reads global skills only from ~/.gemini/config/skills; ~/.gemini/antigravity/skills is left alone.
6. BrainLayer: check BrainBar + brain_search; never block setup on it.
7. Report: one line per release-gate result, including REFUSE and failures.

Never: enable a feature without consent · write config with a nonexistent path · overwrite config without asking · replace ~/.codex/config.toml · proceed without all 6 tools · clone without a confirmed workspace path, or when machineRole is missing/unrecognised/daemon-host, or an installable/unclassified repo · --enforce before showing --diff · commit .claude.local.md.

List installed skills

"What skills do I have?", "search skills for git", "show my skills": run the scan in references/list-skills.md over ~/.claude/skills/ and present one table per category (Infrastructure / Domain / Custom) with name, description, source, workflow count. Show descriptions, never full SKILL.md bodies. This is not for invoking a skill; invoke that skill directly. The repo's catalog truth is node scripts/ci/check-skill-library.mjs.

Required CLIs

# Check all at once
for cmd in gh op bun cr git jq fswatch; do
  which $cmd >/dev/null 2>&1 && echo "✅ $cmd" || echo "❌ $cmd — needs install"
done

Skill Symlinks

Release skills live in $HOME/.golems/current/skills/golem-powers/. The discovery root depends on which CLI you use:

The release installer links the separate Claude and agents lists in skills/catalog.json; shared helpers without SKILL.md are never installed as skills. Existing foreign-repo links and real directories are preserved. Use the release installer to keep this curated set instead of linking every library directory:

curl -fsSL https://raw.githubusercontent.com/EtanHey/golems/master/scripts/release/install.sh | sh -s -- --channel nightly
# Opt in to migrating only links that resolve into a golems checkout's skills/:
# append --replace-checkout-links to the command above.

The catalog mirrors the owner's per-root installed-skill scan; the library checker still counts all available skills. Updates remove only retired release-owned links. For legacy commands/ cleanup, use bash <golem-install-dir>/scripts/cleanup-legacy-commands.sh --golems-dir <clone>.

For authorized pinned design skills, use the separate vendor mode in setup-symlinks. It installs only the providers in skills/vendor/manifest.json; do not glob vendor folders into the golem-powers catalog or expose them through shared roots.

MCP Servers

Wire these MCPs via ~/.mcp.json (at $HOME/Gits/ for cross-repo access):

# Verify MCP binaries
which brainlayer-mcp || echo "Run: cd $HOME/Gits/brainlayer && bun link"
which voicelayer-mcp || echo "Run: cd $HOME/Gits/voicelayer && bun link"

Context7 is opt-in per repository. Do not install it globally or for infra seats; configure it only when a project explicitly requests library documentation lookup.

Global CLAUDE.md

Ensure ~/.claude/CLAUDE.md exists with global instructions. Template lives at:

$ORCHESTRATOR_REPO/standards/

1Password Items Needed

Agents never call op for a routine check: each call asks Etan for Touch ID. Verify the key files instead, and check 1Password only when Etan is there to approve:

bash scripts/validate.sh                    # key files present and private; no op calls
bash scripts/validate.sh --with-1password   # also op checks; Touch ID prompts, Etan present

Golem Terminal (Optional)

Native macOS terminal for running agents:

cd $HOME/Gits/golem-terminal && bash install.sh

Config lives at: ~/Library/Application Support/golem-terminal/golems.toml

Validation Checklist

echo "=== Golem Setup Validation ==="
echo "CLIs:"
for cmd in gh op bun cr git jq; do which $cmd >/dev/null 2>&1 && echo "  ✅ $cmd" || echo "  ❌ $cmd"; done

echo "Skills (Claude Code — ~/.claude/skills/):"
skill_count=$(ls ~/.claude/skills/ 2>/dev/null | wc -l | tr -d ' ')
[ "$skill_count" -gt "30" ] && echo "  ✅ $skill_count skills in ~/.claude/skills/" || echo "  ❌ Only $skill_count skills in ~/.claude/skills/ (expected 40+). Run the symlink step above."

echo "Skills (Codex/other — ~/.agents/skills/):"
agents_count=$(ls ~/.agents/skills/ 2>/dev/null | wc -l | tr -d ' ')
[ "$agents_count" -gt "5" ] && echo "  ✅ $agents_count skills in ~/.agents/skills/" || echo "  ⚠️  Only $agents_count skills in ~/.agents/skills/ (run setup-symlinks for your CLI)"

echo "MCPs:"
which brainlayer-mcp >/dev/null 2>&1 && echo "  ✅ brainlayer-mcp" || echo "  ❌ brainlayer-mcp"
which voicelayer-mcp >/dev/null 2>&1 && echo "  ✅ voicelayer-mcp" || echo "  ❌ voicelayer-mcp"

echo "Codex safety defaults (-s is a compatibility no-op):"
awk '/^[[:space:]]*\[/{exit} /^[[:space:]]*approval_policy[[:space:]]*=[[:space:]]*"never"[[:space:]]*$/{found=1} END{exit !found}' ~/.codex/config.toml 2>/dev/null && echo "  ✅ approval_policy = never" || echo "  ❌ Set top-level approval_policy = \"never\" in ~/.codex/config.toml"
awk '/^[[:space:]]*\[/{exit} /^[[:space:]]*sandbox_mode[[:space:]]*=[[:space:]]*"danger-full-access"[[:space:]]*$/{found=1} END{exit !found}' ~/.codex/config.toml 2>/dev/null && echo "  ✅ sandbox_mode = danger-full-access" || echo "  ❌ Set top-level sandbox_mode = \"danger-full-access\" in ~/.codex/config.toml"

echo "=== Done ==="

Troubleshooting

Homebrew not installed:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1Password CLI not connecting to app:

1. Open 1Password 8 desktop
2. Settings → Developer → Enable CLI integration
3. Enable biometric unlock for CLI

Skills not appearing in Claude Code (slash command autocomplete):

# CC reads from skills/, NOT commands/
ls ~/.claude/skills/
# If empty or missing skills, re-run the symlink step above.
# If skills are still under commands/, migrate them. This handles all three legacy
# shapes (symlink into golems, golems-cli backfill into skills/, real mkdir'd dir)
# and also clears dead symlinks out of ~/.claude/skills/:
cleanup="${GOLEMS_DIR:-$HOME/Gits/golems}/skills/golem-powers/golem-install/scripts/cleanup-legacy-commands.sh"
bash "$cleanup" --dry-run
bash "$cleanup"

Skills not appearing in Codex:

ls ~/.agents/skills/
ls ~/.codex/skills/  # Should symlink into ~/.agents/skills/
# Re-run: ln -sf ~/.agents/skills/<skill> ~/.codex/skills/<skill>

brainlayer-mcp not found:

cd $HOME/Gits/brainlayer && bun install && bun link