git:20260904.4176ecd to git:20260905.ca45c0e

# System & Environment Setup (opt/scripts/system)

This directory contains scripts for configuring the operating system, environment variables, and base development tools.

## Scripts

- `sync-skills.sh`: **Canonical skill linker for both assistants.** Discovers every `SKILL.md` (under `src/*/`, `sdk/*/`, `ai/skills/*`, `.agents/skills/*`) and links it into **both** `~/.gemini/config/skills` (Antigravity CLI) and `~/.claude/skills` (Claude Code). Exposed as the `sync-skills` alias; pass `--build` to also rebuild core binaries (`gss`, `tmux-mgr`, `wol`).

- `sync-plugins.sh`: **Ensure-only sync of AI-assistant plugins** from the `ai/plugins.yaml` manifest. Installs + enables the listed Claude plugins (via `claude plugin install`/`enable`) and installs the listed Antigravity plugins (via `agy plugin install`); never removes anything. Exposed as the `sync-plugins` alias; pass `--dry-run` to preview. Parsed with mikefarah `yq`. Companion test: `sync-plugins_test.sh`.

- `bump-sdk-version.sh`: **Conventional-commit SDK version bumper (issue #139).** For each `sdk/<tool>/` module (a dir with both `go.mod` and `VERSION`), computes the next semver from the conventional-commit subjects of commits touching the module's *source* since its last `sdk/<tool>/v<X.Y.Z>` tag (`feat:`→minor, `!`/`BREAKING CHANGE`→major, else patch). `--check` (default; `make sdk-bump`) reports needed bumps and exits 1 if any; `--write` applies them. Idempotent and excludes the `VERSION` file from the source-delta check so the CI auto-bump loop terminates; respects a manually pre-bumped VERSION; leaves untagged modules to the tagger. Drives `.github/workflows/sdk-auto-bump.yml`. Companion test: `bump-sdk-version_test.sh`.

- `antigravity_install.sh`: Installs the Antigravity CLI (`agy`, successor to the retired Gemini CLI) via Google's checksummed bootstrapper, removes the retired `@google/gemini-cli` npm package, and generates `~/.antigravity.profile`.

- `install_antigravity_skills.sh`: Antigravity-specific config, mirroring `install_claude_skills.sh` (agy-parity, `docs/mbo/designs/agy-parity.md`): guard hooks copied into `~/.gemini/config/hooks/`; the repo's `guards` entry rendered from `ai/antigravity/hooks.json.template` and **merged** into `hooks.json` (other named hooks such as herdr's survive); `~/.gemini/antigravity-cli/settings.json` seeded once from `ai/antigravity/settings.json.template` and the forced subset (`settings.forced.json`: statusLine + deny/ask replaced, allow unioned) re-applied every run via `apply-forced-settings.sh`; `aliases.sh` copied; the local `dotfiles` plugin rendered (see `render-agy-plugin.sh`) and enabled in `~/.gemini/config/config.json`; legacy Gemini cleanup. Skill links are handled by `sync-skills.sh`. Companion test: `install_antigravity_skills_test.sh`.

- `render-agy-plugin.sh`: **Renders the repo's Claude slash commands and account memories as a local Antigravity plugin** (`<plugin-dir>/plugin.json`, `commands/<name>.toml` from `ai/claude/commands/*.md`, `rules/AGENTS.md` from the `scope: account` files in `ai/claude/memory/`). Pure function of the two repo dirs (bash 3.2 + awk/sed, no jq): frontmatter stripped, Claude `!`cmd`` injection lines rewritten as instructions, `$ARGUMENTS` rewritten as prose (agy substitutes no token), stale TOMLs removed on re-render. Invoked by `install_antigravity_skills.sh`. Companion test: `render-agy-plugin_test.sh`.

- `gemini_teardown.sh`: **Consent-based cleanup of retired Gemini CLI leftovers** discovered on the host (npm package/binary, `gemini()` alias file, `~/.gemini.profile`, stale rc source lines). Prompts `[y]es / [n]ot now / [k]eep forever` with the turn-down references; `[k]` persists a marker (`~/.config/antigravity/gemini-keep`) so install.sh never asks again (`--reset` re-enables). `--yes` for unattended cleanup; non-TTY runs only report. Never touches `~/.gemini` itself (Antigravity reuses it). Companion test: `gemini_teardown_test.sh`.

- `strip-agy-rc-appends.sh`: **Repo-hygiene guard for agy's shell setup.** The agy bootstrapper appends a hardcoded-`$HOME` PATH export through our symlinked rc files into the repo working tree; this strips that block from symlinked (repo-managed) rc files only — the repo profiles already export `~/.local/bin` portably. Runs automatically at the end of `antigravity_install.sh`; rerun after an agy self-update re-appends it. Companion test: `strip-agy-rc-appends_test.sh`.

- `claude_install.sh`: Installs (or updates) the Claude Code CLI binary.

- `install_claude_skills.sh`: Claude-specific config (settings.json, slash commands, hooks, aliases). Skill links are handled by `sync-skills.sh`. Also invokes `provision-claude-memory.sh`.

- `provision-claude-memory.sh`: **Account-scoped memory provisioner (issue #134).** Seeds the repo's `scope: account` Claude memories (`ai/claude/memory/*.md`) into this machine's live project-memory store (`~/.claude/projects/<computed-slug>/memory/` — the slug is derived per-machine via `pwd -P`). Seed-and-preserve: copies account files, **never** clobbers host-local memories, regenerates `MEMORY.md` from the union. Mirrors `apply-forced-settings.sh` (standalone + tested). Companion test: `provision-claude-memory_test.sh`. Design: `docs/mbo/designs/memory-provisioning.md`.

- `install_ai_teams.sh`: **Transforms `ai/teams/` personas into native agents for all three tools** (Claude `~/.claude/agents/teams/`, Antigravity `~/.config/antigravity/agents/`, Ollama Modelfiles). Resolves each persona's `tier:` via `ai/teams/model-map.yaml`, composes the system prompt from `_partials/`, and compiles a routing `description`. Idempotent; graceful-skip per tool. Exposed as the `sync-teams` alias (`--dry-run`/`--tool`). Validates first via `ai/teams/validate.sh`. Companion test: `install_ai_teams_test.sh`.

- `install_sops.sh`: Installs the `sops` secrets-management binary into `~/opt/bin` (Linux/WSL fetches the official release; macOS uses the Brewfile).

- `install_yq.sh`: Installs the mikefarah `yq` (YAML processor) binary into `~/opt/bin` (Linux/WSL fetches the official release; macOS uses the Brewfile/`packages.tsv`). The apt `yq` is the incompatible kislyuk Python variant, so it is intentionally not used. Needed by `sync-plugins.sh`.

- `install_k8s_tools.sh`: Installs the Kubernetes toolchain — `kubectl`, `helm`, `kind` — into `~/opt/bin` (Linux/WSL fetches the official release binaries; macOS uses `packages.tsv`/brew). apt has no `kind` package and kubectl/helm apt repos lag upstream. Resolves latest stable versions at run time; override with `KUBECTL_VERSION`/`HELM_VERSION`/`KIND_VERSION`, force reinstall with `K8S_TOOLS_FORCE=1`. Needed by local k8s dev flows (kind cluster → helm install → kubectl).

- `install_herdr.sh`: Installs [herdr](https://github.com/herdrdev/herdr) (Apache-2.0; terminal workspace manager for coding agents) into `~/opt/bin` on every platform (static release binaries for linux/macOS × x86_64/aarch64; 32-bit ARM has no upstream build and is skipped). **Tracks the latest release** by default so `fleet update` keeps all hosts on one version (herdr's client/server protocol is versioned); pin with `HERDR_VERSION=x.y.z`, force with `HERDR_FORCE=1`. Every download is verified against the SHA-256 herdr publishes in `herdr.dev/latest.json` — fail-closed. Second mode `install_herdr.sh integrations` runs `herdr integration install` for the agent CLIs present (`HERDR_INTEGRATIONS`, default `claude antigravity-cli`); it is a config-phase step (ordering relative to `install_antigravity_skills.sh` no longer matters — that script merges `hooks.json` and preserves herdr's entry). gff: `install.tools.herdr` (deps) + `install.tools.herdr-integrations` (config). Companion test: `install_herdr_test.sh`. Research: `docs/mbo/designs/herdr.md`.

- `setup_gh_apt_repo.sh`: Registers GitHub CLI's official apt repo + signing key **and pins it above Ubuntu Pro ESM** so `gh` installs the latest upstream release. The pin is load-bearing: ESM pins everything it carries to priority 510, above the 500 the official repo would get, which silently held `gh` at 2.45.0 and broke `gh pr edit` (issue #255). Idempotent, and re-running heals a host that predates the pin; called automatically by `pkg-install-apt`. Force a key/repo refresh with `GH_REPO_FORCE=1`. Tests: `setup_gh_apt_repo_test.sh`.

- `nvm`: Helper for Node Version Manager setup.

- `google-cli-setup.sh`: Installs/updates gcloud, the Antigravity CLI (only when absent — `antigravity_install.sh` owns the install), and the `gws` Workspace CLI; `status` subcommand reports their health.

- `setup_jtop.sh`: Installs and configures jetson-stats (jtop) for NVIDIA Jetson devices.

- `terminal-theme.sh`: Configures terminal colors and themes.

- `gnome-desktop-defaults.sh`: The **gsettings half** of the macOS-style keyboard layout — the desktop-level ACTIONS that `macos-keys-linux.sh` deliberately forwards to GNOME as a real `<Super>` chord: `Cmd+Space` (Activities search), `Cmd+M`/`Cmd+H` (minimize), an inert lone-Cmd tap (`overlay-key` cleared, as on macOS), and moving the message tray to `<Super>n` so it cannot swallow paste or minimize. It also **resets gnome-terminal copy/paste to stock `Ctrl+Shift+C/V`** on machines where a pre-keyd version bound them to `<Super>c/v` — keyd's `app.conf` emits the stock chords, so a Super bind there means `Cmd+V` prints `^V`. Never bind those two keys here. Idempotent, hand-runnable, and a no-op off a writable GNOME session (CI, docker, WSL, plain SSH, macOS). Gated by `install.desktop.gnome-keys` **and** the cross-OS `keyboard.macos.enabled`.

- `macos-keys-linux.sh`: The **keyd half** of the same feature — installs [keyd](https://github.com/rvaiya/keyd) (built from a pinned tag; not packaged for Ubuntu 24.04) plus `opt/etc/keyd/*.conf`, so `Cmd+C/V/X/A/Z` and the macOS navigation chords work in **every** GUI app, not just the terminal — keyd rewrites events below X11/Wayland, which gsettings cannot do. **Fail-closed:** verifies `keyd-application-mapper` can detect the focused window *before* installing any config, and rolls back if the mapper cannot reach keyd's socket — because keyd without the mapper turns `Cmd+C` into SIGINT inside a terminal. `--doctor` reports state, `--uninstall` reverts. Panic chord: hold Backspace+Esc+Enter. Gated by `install.desktop.macos-keys` **and** `keyboard.macos.enabled`. See [docs/macos-keys.md](../../../docs/macos-keys.md).

- `perf-toggle.sh`: Toggles system performance modes (e.g., on Jetson).

- `enable-vmx.sh`: Helper to check/enable virtualization support.

- `coco_install.sh`: Installer for the COCO dataset tools or similar.

- `crouton-alias.sh`: Aliases for Crouton (Chromebook) environments.

- `retire-ahk-voice-macro.sh`: **WSL migration helper.** Removes the old AutoHotkey Copilot-key voice macro from a machine's deployed `macos.ahk` (backs it up locally, re-deploys the cleaned copy, restarts AutoHotkey). One-off cleanup for hosts provisioned before voice dictation moved to Wispr Flow. Idempotent; `--dry-run` to preview. See `opt/Desktop/Apps/scripts/WISPR-FLOW.md`.

## Environment Profile

The `antigravity_install.sh` script generates `~/.antigravity.profile`, which is sourced by your shell to provide the Antigravity environment (agy PATH, opt/scripts discovery, tmux helpers). The legacy `~/.gemini.profile` is removed by the same script.