Of Setup

---
name: of-setup
description: Set up, install, or configure the OpenFOAM CFD Suite on this machine. Use on first run of the plugin, when the user says "of-setup", "set up the OpenFOAM suite", "adapt to this machine", or after an OpenFOAM upgrade or a plugin update. Detects the host mode (Windows+WSL or native Linux), locates the OpenFOAM installation, writes the machine config (of-env.sh), generates skills/of-sim/references/environment.md, patches allowed-tools, seeds the case registry, and offers a 1-minute validation benchmark.
---

# of-setup: adapt the suite to this machine

Everything below is idempotent - re-running is safe and overwrites generated files.
After a marketplace plugin UPDATE the plugin cache is replaced: environment.md and the
allowed-tools frontmatter patch are wiped - re-run of-setup to regenerate them.
of-env.sh and the case registry live OUTSIDE the plugin and survive.

## Machine layer (what this skill owns)

| artifact | location | survives plugin update |
|---|---|---|
| of-env.sh | `~/.config/openfoam-claude-suite/of-env.sh` (in the distro / Linux home) | yes |
| environment.md | `<suite>/skills/of-sim/references/environment.md` | NO - regenerate |
| allowed-tools patch | frontmatter of of-sim/of-post/of-doctor SKILL.md (mode A only) | NO - regenerate |
| case registry | `$FOAM_RUN/case-registry.md` | yes |

Wrapper scripts resolve of-env.sh in this order (do not change it):
`$OF_SUITE_ENV` (explicit path) -> `<own script dir>/of-env.sh` ->
`~/.config/openfoam-claude-suite/of-env.sh` -> autodetect (newest of
`/opt/OpenFOAM-*/etc/bashrc`, `/usr/lib/openfoam/openfoam*/etc/bashrc`).
of-setup writes to the `~/.config` location so the config survives plugin updates.
of-env.sh sets exactly: `OF_BASHRC=<path to OpenFOAM etc/bashrc>` (required) and
optionally `OF_NPROC_CAP=<max parallel ranks>`. Template:
`<suite>/skills/of-sim/scripts/of-env.example.sh`.

## Procedure

1. **Locate the suite.** Suite root = two directories up from this SKILL.md (the dir
   containing `skills/of-setup` and `skills/of-sim`). Wrapper scripts dir
   SCRIPTS = `<suite>/skills/of-sim/scripts` - verify `ofrun.sh` exists there.

2. **Detect host mode.** Windows host (platform win32, `wsl.exe` on PATH) -> **mode A**
   (Windows + WSL: wsl.exe --exec invocation layer, UNC file authoring, CRLF stripping).
   Otherwise Linux -> **mode B** (native: invoke wrappers directly as `bash <SCRIPTS>/...`).
   In mode A the in-distro view of SCRIPTS is needed for every wsl call:
   `C:/Users/<you>/...` -> `/mnt/c/Users/<you>/...`;
   `\\wsl.localhost\<distro>\<p>` -> `/<p>`. Call it SCRIPTS_WSL.

3. **Locate OpenFOAM.**
   Mode A: list distros with `wsl.exe -l -q` (output may be UTF-16 - strip NULs, e.g.
   `wsl.exe -l -q | tr -d '\0'`). Discard non-Linux entries (docker-desktop*,
   rancher-desktop, podman-*). If more than one plausible distro remains, AskUserQuestion
   (recommend the WSL default). Then inside the chosen distro:
   ```bash
   MSYS_NO_PATHCONV=1 wsl.exe -d <distro> --exec bash -c 'ls -d /opt/OpenFOAM-*/etc/bashrc /usr/lib/openfoam/openfoam*/etc/bashrc 2>/dev/null'
   ```
   Mode B: run the same `ls -d` locally.
   Newest version wins (sort -V, take last). Several candidates that are not clearly
   ordered -> AskUserQuestion. None -> report "OpenFOAM not found" with the paths
   searched, suggest another distro or installing OpenFOAM v2412, and STOP.
   If the detected version is not v2412, warn: the suite is tuned for v2412 but mostly
   applies to nearby versions.
   Also record the in-distro home: `wsl.exe -d <distro> --exec bash -c 'echo $HOME'`
   (mode B: `$HOME`).

4. **Write of-env.sh** to `~/.config/openfoam-claude-suite/of-env.sh` (overwrite):
   ```sh
   # openfoam-claude-suite machine config - generated by /of-setup; regenerate by re-running it
   OF_BASHRC=<detected bashrc path>
   # OF_NPROC_CAP=<N>   # optional: cap parallel ranks below nproc
   ```
   Leave OF_NPROC_CAP commented unless the user asked to reserve cores.
   Mode A: Write tool to `\\wsl.localhost\<distro>\home\<user>\.config\openfoam-claude-suite\of-env.sh`,
   then strip CRLF inside the distro:
   `wsl.exe -d <distro> --exec bash -c "sed -i 's/\r$//' /home/<user>/.config/openfoam-claude-suite/of-env.sh"`.
   Mode B: Write tool to the path directly.

5. **Smoke test.** Run the env wrapper through the proper invocation:
   ```bash
   # mode A
   MSYS_NO_PATHCONV=1 wsl.exe -d <distro> --exec bash <SCRIPTS_WSL>/ofrun.sh env
   # mode B
   bash <SCRIPTS>/ofrun.sh env
   ```
   The last output line is the sentinel `__OFRC=<rc>__` - parse it, not the exit code
   (wsl.exe exit codes are unreliable through MSYS). Require `__OFRC=0__` and record:
   WM_PROJECT_VERSION, FOAM_APPBIN app count (a full install has hundreds; 0 means the
   bashrc sourced but the build is absent), FOAM_RUN, cores, and mpirun / gnuplot /
   pvpython presence. On failure, diagnose BEFORE proceeding:
   - `WM_PROJECT_VERSION=MISSING` -> OF_BASHRC path wrong or unreadable; redo step 3.
   - `$'\r': command not found` -> CRLF survived; re-run the sed strip.
   - wsl.exe "no such distribution" -> distro name typo (names are case-sensitive).
   - Empty output (mode A) -> known MSYS intermittency; retry once with the exact
     `--exec` form above (never `wsl.exe -- bash -c`).
   Then one probe call for the remaining machine facts:
   ```bash
   ... ofrun.sh sh - 'whoami; nproc; free -h | grep Mem; echo $FOAM_TUTORIALS; echo $FOAM_USER_APPBIN; ls $FOAM_USER_APPBIN 2>/dev/null | wc -l; ls $FOAM_USER_APPBIN 2>/dev/null | head -15'
   ```

6. **Generate environment.md.** Write (Write tool, overwrite)
   `<suite>/skills/of-sim/references/environment.md` in the EXACT shape of
   `<suite>/skills/of-sim/references/environment.example.md`, filled with the probed
   facts: distro/user/cores/RAM, OpenFOAM install path + app count, user appbin
   inventory, FOAM_RUN, tutorials path, helper-script invocation prefix, Windows UNC
   view (mode A), extras (mpirun/gnuplot/pvpython). Include the install inventory:
   FOAM_APPBIN app count; the first ~15 entries of `$FOAM_USER_APPBIN` plus total count,
   with the warning that `$FOAM_USER_APPBIN` is FIRST on PATH so user-built apps shadow
   stock apps of the same name; compiled optional modules if evident from the appbin
   listings; and the concrete invocation prefix for THIS machine
   (mode A: `MSYS_NO_PATHCONV=1 wsl.exe -d <distro> --exec bash <SCRIPTS_WSL>/<script>.sh ...`;
   mode B: `bash <SCRIPTS>/<script>.sh ...`).

7. **allowed-tools patch (mode A only).** With the Edit tool, add to the frontmatter of
   `skills/of-sim/SKILL.md`, `skills/of-post/SKILL.md`, `skills/of-doctor/SKILL.md`
   (insert after the description line; if an allowed-tools line already exists, replace it):
   ```
   allowed-tools: Bash(MSYS_NO_PATHCONV=1 wsl.exe -d <distro> --exec bash:*), Bash(wsl.exe -d <distro> --exec bash:*)
   ```
   with the real distro name substituted. Mode B: skip - the pattern exists to
   pre-approve the wsl.exe invocation layer; on native Linux the wrappers run as plain
   bash commands and allowlisting `Bash(bash:*)` would be far too broad. The user
   approves wrapper calls through the normal permission flow instead.

8. **Case registry.** `ofrun.sh env` already created `$FOAM_RUN`. Seed the registry ONLY
   if absent (it is user data - never overwrite):
   ```bash
   ... ofrun.sh sh - '[ -f "$FOAM_RUN/case-registry.md" ] && echo EXISTS || printf "%s\n" "# OpenFOAM case registry" "" "| date | case | solver | cells | verdict | result |" "|---|---|---|---|---|---|" > "$FOAM_RUN/case-registry.md"'
   ```

9. **Offer validation.** AskUserQuestion: run the ~1-minute validation benchmark now?
   (recommended on first setup). If yes, run `<SCRIPTS>/val-cavity-ghia.sh` through the
   step-5 invocation (mode A: foreground with timeout near 600000 ms). It runs the
   lid-driven cavity at Re=100 and compares the centerline velocity profile against
   Ghia et al. (1982); PASS threshold max abs centerline-velocity error < 0.03
   (3% of U_lid, per ghia_compare.py). Report its verdict and the comparison
   plot path; on FAIL, point to the of-doctor skill.

10. **Setup summary.** Print: of-env.sh path + contents; environment.md path;
    allowed-tools patched files (mode A) or why skipped (mode B); registry path
    (seeded or pre-existing); smoke-test facts (version, app count, cores, extras);
    validation verdict if run. Remind the user:
    - after an OpenFOAM upgrade: re-run `/of-setup` (refreshes OF_BASHRC and environment.md);
    - after a plugin update: re-run `/of-setup` (environment.md and the allowed-tools
      patch were wiped with the plugin cache; of-env.sh and the registry survived).