pai CLI shim references PAI/Tools/ but install ships PAI/TOOLS/ — breaks on Linux

[NorthwoodsSentinel]

pai CLI shim references PAI/Tools/ but install ships PAI/TOOLS/ — breaks on Linux

Summary

The pai command-line shim at /usr/local/bin/pai and the bashrc alias both reference ${PAI_ROOT}/PAI/Tools/pai.ts (mixed case). The installed PAI tree ships the tools directory as PAI/TOOLS/ (all uppercase). Linux is case-sensitive — the shim doesn't resolve. macOS users don't see this because HFS+ and APFS default to case-insensitive.

Affects

PAI v5.0.0 on any case-sensitive filesystem (Linux distros, including WSL2 on Windows). All Linux installs are at minimum suspect; reproduced on Lares running PAI 5.0.0 (WSL2 Ubuntu).

Reproduction

ls /root/.claude/PAI/TOOLS/pai.ts    # exists
ls /root/.claude/PAI/Tools/pai.ts    # ENOENT — no such file or directory

cat /usr/local/bin/pai
# Output: #!/bin/bash
#         exec bun "/root/.claude/PAI/Tools/pai.ts" "$@"
# (or similar — references the lowercase path)

grep 'pai' ~/.bashrc | grep -i alias
# Output: alias pai='bun /root/.claude/PAI/Tools/pai.ts'

pai
# bun: error opening /root/.claude/PAI/Tools/pai.ts: No such file or directory
# (or similar — depends on which shim/alias was tried first)

Local workaround

ln -s TOOLS /root/.claude/PAI/Tools

A same-name symlink at the lowercase path makes both casings resolve. Tested working on Lares (Linux, WSL2 Ubuntu) on 2026-05-21.

Root cause

The PAI source/release tooling produces a TOOLS/ directory but the installer-templated shim and bashrc alias hardcode Tools/. Both layers exist in the public release; the inconsistency was probably introduced when the source tree directory was renamed (or the shim was written) without updating both places.

Filesystem semantics:

• macOS HFS+/APFS default: case-insensitive (preserves case in metadata, lookups are case-insensitive). Tools/ and TOOLS/ resolve to the same entry.
• Linux ext4/btrfs/zfs/xfs: case-sensitive. Tools/ and TOOLS/ are distinct.
• WSL2 mounting: respects underlying filesystem (case-sensitive on the WSL2 root).

This is the classic class of "works on Mac, breaks on Linux" cross-platform bug.

Proposed fix (discussion needed before PR)

Pick ONE canonical casing and enforce it across:

1. Source tree directory name (PAI/TOOLS/ or PAI/Tools/)
2. The pai system shim (/usr/local/bin/pai)
3. The bashrc alias (alias pai='bun ${PAI_ROOT}/PAI/.../pai.ts')
4. The CLAUDE.md context-routing table reference (currently says ~/.claude/PAI/Tools/)
5. Any other documentation references (README, docs site, etc.)

Recommendation

Lowercase Tools/ — three reasons:

1. The convention in CLAUDE.md prose already says ~/.claude/PAI/Tools/. Aligning the source tree to match the prose is less disruptive than rewriting all the docs.
2. Tools is a non-acronym word; mixed-case is the typical convention for non-acronym directories (sibling examples in the same install: PAI/USER/, PAI/MEMORY/, PAI/DOCUMENTATION/ — though those ARE all-caps; this argues the other direction; see below).
3. The all-caps style across PAI/ siblings (USER/, MEMORY/, DOCUMENTATION/, ALGORITHM/, HOOKS/) suggests TOOLS/ was intentional. If you keep it TOOLS/, every reference to Tools/ in shim/alias/docs needs to update.

Alternative — keep TOOLS/ and fix the references

If maintaining the all-caps convention is intentional:

• Update pai shim to reference PAI/TOOLS/pai.ts
• Update bashrc alias template to match
• Update CLAUDE.md prose references (~/.claude/PAI/Tools/ → ~/.claude/PAI/TOOLS/)
• Add an installer migration step that rewrites the bashrc alias on upgrade

Either way — migration step

A one-shot installer migration is needed for existing installs, OR the installer adds a Tools → TOOLS symlink (or vice versa) as a permanent compat shim.

Why this matters

PAI 5.0 on Linux fails its own pai command out of the box on every new install. Workaround is one symlink but it requires the user to know to make it. Every new Linux PAI user hits this.

Filed by

Rob Chuvala via Margin (Lares-side DA), 2026-06-03
Originally captured 2026-05-21 in fleet-internal queue at project_pai_upstream_bugs_queue.md per CeeCee's protocol; surfacing now after vacation completed.

Discussion preference

Would like to align on canonical casing BEFORE opening a PR — the fix touches multiple files and the right choice depends on which convention you want to lock in. Happy to open the PR with whichever direction you prefer.