diff --git a/docs/research/hpc_os_compatibility.md b/docs/research/hpc_os_compatibility.md
new file mode 100644
index 000000000..329e174b5
--- /dev/null
+++ b/docs/research/hpc_os_compatibility.md
@@ -0,0 +1,1043 @@
+# chemsmart HPC OS compatibility audit
+- Report date: 2026-05-10
+- Auditor persona: HPC OS Management Specialist
+- Audit target: commit `20cbcdb9`
+- Current repo head in this worktree: `36f13c6e`
+- Scope: `chemsmart agent` multi-tool pipeline added in W1a/W1b/W2a/W2b
+- Constraint: no code changes; research only
+## Audit framing
+- I audited the code and packaging state at commit `20cbcdb9`, because that is
+the user-specified pipeline head.
+- I also read the current `AGENTS.md` for repo conventions.
+- `AGENTS.md` does not exist at commit `20cbcdb9`; I used the current file only
+as a workflow/conventions guide, not as evidence about the target pipeline.
+- Required local files reviewed:
+  - `pyproject.toml` at `20cbcdb9`
+  - `environment.yml` at `20cbcdb9`
+  - `README.md` at `20cbcdb9`
+  - `chemsmart/agent/providers.py` at `20cbcdb9`
+  - `chemsmart/agent/transport.py` at `20cbcdb9`
+  - `chemsmart/agent/cli.py` at `20cbcdb9`
+  - `chemsmart/agent/core.py` at `20cbcdb9`
+  - `chemsmart/agent/tools.py` at `20cbcdb9`
+  - `chemsmart/agent/tui/app.py` at `20cbcdb9`
+  - `chemsmart/agent/tui/styles.tcss` at `20cbcdb9`
+  - `chemsmart/agent/tui/widgets/header.py` at `20cbcdb9`
+  - `chemsmart/settings/server.py` at `20cbcdb9`
+  - `chemsmart/settings/submitters.py` at `20cbcdb9`
+  - current `AGENTS.md`
+- Bottom-line upfront:
+  - ABI-wise, the pipeline is broadly runnable on modern Linux login-node OSes
+in scope.
+  - Operationally, it does **not** run “without issue” on common shared HPC
+login nodes.
+  - The biggest problems are not GLIBC.
+  - The biggest problems are:
+  - Python 3.10+ is not the default system Python on EL8, EL9, or SLES 15.
+  - the documented credential flow is broken by a hard-coded absolute `api.env` path in
+    `providers.py`.
+  - `rich` is imported by the agent CLI but is not declared as a direct dependency in
+    `pyproject.toml`.
+  - `run_local` and long-lived Textual sessions are poor fits for shared login node
+    acceptable-use policies at NERSC, TACC, and OLCF.
+  - outbound HTTPS to `factchat-cloud.mindlogic.ai` is mandatory.
+  - `submit_hpc` over SSH assumes host aliases derived from the server YAML filename,
+    which is brittle on real clusters.
+## 1. Pipeline Dependency Audit
+### 1.1 What the audited pipeline actually needs
+From the audited commit, the agent stack is split across four layers.
+1. CLI and rendering layer.
+   - `click`
+   - `rich`
+2. validation and provider layer.
+   - `pydantic>=2`
+   - `python-dotenv>=1`
+   - `openai>=1`
+   - `anthropic>=0.40`
+3. chemistry/job layer.
+   - `ase==3.24.0`
+   - `numpy~=1.26.4`
+   - `scipy==1.15.2`
+   - `PyYAML`
+   - existing chemsmart Gaussian/ORCA code
+4. TUI extra.
+   - `textual>=0.80,<1.0`
+   - `watchdog>=3,<5`
+   - `pyperclip`
+### 1.2 Important packaging observations from the local audit
+- `pyproject.toml` at `20cbcdb9` declares:
+  - `requires-python = "~=3.10"`
+  - main deps include `anthropic`, `openai`, `python-dotenv`, `pydantic`
+  - TUI extra includes `textual`, `watchdog`, `pyperclip`
+- `environment.yml` pins `python=3.10` and includes `anthropic`, `openai`,
+`pydantic`, and `python-dotenv` in the conda dependency list.
+- The agent CLI imports `rich` at module import time in
+`chemsmart/agent/cli.py`.
+- `rich` is **not** declared in the base dependencies or the `agent-tui` extra.
+- Therefore:
+  - a minimal `pip install -e .` may fail to import `chemsmart agent` if `rich`
+is not already present from some unrelated package.
+  - a full `.[agent-tui]` install probably pulls `rich` transitively via
+`textual`, but that is accidental, not explicit.
+- On clusters, accidental transitive dependencies are a recurring support
+headache because module stacks, wheel caches, and offline mirrors are rarely identical
+across sites.
+### 1.3 Important runtime-path observations from the local audit
+- `providers.py` hard-codes:
+  - `_API_ENV_PATH = "/Users/hongjiseung/developer/chemsmart/api.env"`
+- `README.md` instructs the user to:
+  - `cp api.env.example api.env`
+- Those two things do not match.
+- On any HPC system, the documented default credential path is therefore broken
+unless the user does one of the following:
+  - exports `ai_api_key` directly in the shell environment, or
+  - creates the exact hard-coded path, which is unrealistic on shared systems.
+- This is not an OS ABI problem.
+- It is a portability problem that will show up on every site.
+### 1.4 File-system and session-path observations from the local audit
+- Agent session root defaults to:
+  - `~/.chemsmart/agent/sessions`
+- Server/user config roots live under:
+  - `~/.chemsmart/server`
+  - `~/.chemsmart/gaussian`
+  - `~/.chemsmart/orca`
+- `dry_run_input(job)` writes input files into `job.folder`.
+- `run_local(job)` writes:
+  - `<label>.stdout`
+  - `<label>.stderr`
+  - plus program outputs generated by `job.run()`.
+- `submit_hpc(job)` writes a submit script and uses either:
+  - local dry-run transport, or
+  - SSH-based submission transport.
+### 1.5 SSH transport observations from the local audit
+`transport.py` does not carry an explicit cluster hostname field.
+It derives the SSH target from `server.name`, which itself is the basename of the server
+YAML path.
+Operationally that means:
+- `foo.yaml` becomes host `foo`
+- `shared.yaml` becomes host `shared`
+- if the name is not `localhost` or `local`, remote submission becomes:
+  - `ssh <basename> "cd <working_dir> && <submit_command> <script>"`
+That is brittle on real HPC sites because:
+- users typically submit directly from the login node with `sbatch`/`qsub`
+- YAML names usually encode policy roles, not DNS names
+- many centers do not guarantee lateral SSH patterns that mirror user YAML names
+- some sites require explicit SSH config aliases to make this work at all
+This does not make the pipeline unusable, but it does make remote submit portability
+materially worse than the OS ABI picture suggests.
+### 1.6 Dependency tree, reduced to what matters for login-node deployability
+Below is the deployability-oriented tree, not the entire chemsmart chemistry stack.
+```text
+chemsmart agent pipeline
+├─ CLI / display
+│  ├─ click==8.1.8                     [pure Python wheel]
+│  ├─ rich                             [pure Python wheel; undeclared direct dep]
+│  │  ├─ markdown-it-py               [pure Python]
+│  │  └─ pygments                     [pure Python]
+│  └─ textual>=0.80,<1.0              [pure Python wheel]
+│     ├─ rich>=13.3.3                 [pure Python]
+│     ├─ markdown-it-py[linkify,...]  [pure Python]
+│     ├─ typing-extensions            [pure Python]
+│     └─ platformdirs                 [pure Python]
+├─ TUI helpers
+│  ├─ watchdog>=3,<5                  [manylinux wheels available]
+│  └─ pyperclip                       [pure Python wheel; Linux clipboard helpers
+│                                      depend on xclip/xsel/GUI stack]
+├─ provider / validation
+│  ├─ pydantic>=2                     [pure Python wheel]
+│  │  ├─ pydantic-core                [compiled manylinux wheel]
+│  │  ├─ annotated-types              [pure Python]
+│  │  ├─ typing-extensions            [pure Python]
+│  │  └─ typing-inspection            [pure Python]
+│  ├─ python-dotenv>=1                [pure Python wheel]
+│  ├─ openai>=1                       [pure Python wheel]
+│  │  ├─ httpx                        [pure Python]
+│  │  ├─ anyio                        [pure Python]
+│  │  ├─ distro                       [pure Python]
+│  │  ├─ jiter                        [compiled Rust wheel on some platforms]
+│  │  └─ pydantic<3,>=1.9            [see above]
+│  └─ anthropic>=0.40                 [pure Python wheel]
+│     ├─ httpx                        [pure Python]
+│     ├─ anyio                        [pure Python]
+│     ├─ distro                       [pure Python]
+│     ├─ jiter                        [compiled Rust wheel on some platforms]
+│     └─ pydantic<3,>=1.9            [see above]
+└─ chemistry / file generation
+   ├─ ase==3.24.0                     [pure Python wheel]
+   │  ├─ numpy>=1.19.5                [compiled manylinux wheel]
+   │  ├─ scipy>=1.6.0                 [compiled manylinux wheel]
+   │  └─ matplotlib>=3.3.4            [compiled/mixed wheel, already in base]
+   ├─ numpy~=1.26.4                   [compiled manylinux wheel]
+   ├─ scipy==1.15.2                   [compiled manylinux wheel]
+   └─ PyYAML                          [compiled manylinux wheel available]
+```
+### 1.7 Binary-wheel versus source-build reality
+For the OSes in scope, the deployability split is straightforward.
+Packages that are effectively pure Python for this audit:
+- `click`
+- `pydantic` itself
+- `python-dotenv`
+- `rich`
+- `textual`
+- `openai`
+- `anthropic`
+- `pyperclip`
+- `ase`
+Packages that matter for binary compatibility:
+- `pydantic-core`
+- `numpy`
+- `scipy`
+- `PyYAML`
+- `watchdog`
+- possibly `jiter` pulled by current `openai` / `anthropic`
+Packages that are likely to force compilers or slower fallback builds only when wheel
+acquisition fails or mirrors are incomplete:
+- `numpy`
+- `scipy`
+- `pydantic-core`
+- `jiter`
+- `PyYAML`
+### 1.8 What resolves today for the loose version specs
+I queried current PyPI metadata in the shell to see what the loose specs would resolve
+to on 2026-05-10.
+Resolved current maxima within the audited specifiers:
+- `pydantic>=2` -> `2.13.4`
+- `textual>=0.80,<1.0` -> `0.89.1`
+- `openai>=1` -> `2.36.0`
+- `anthropic>=0.40` -> `0.100.0`
+- `watchdog>=3,<5` -> `4.0.2`
+- `python-dotenv>=1` -> `1.2.2`
+- `PyYAML` -> `6.0.3`
+Operational implication:
+- the audited code is not locked to the versions it was likely tested with.
+- on sites with frozen wheel mirrors or institutional package proxies, you may
+see resolution drift unrelated to OS.
+- that is a packaging governance issue, not a GLIBC issue.
+### 1.9 Dependency-audit verdict
+- For Ubuntu 22.04, Ubuntu 24.04, and Debian 12, package ABI is not the first
+concern.
+- For EL8/EL9/SLES15-class HPC systems, package ABI is still not the first
+concern.
+- The first concern is getting a Python 3.10+ user environment.
+- The second concern is the broken default credential path.
+- The third concern is shared-login-node policy.
+## 2. HPC OS Compatibility Matrix
+### 2.1 Matrix
+| OS family | Default/site Python picture | GLIBC floor in practice | Linux wheel fit | Conda/micromamba fit | TUI fit on login node | Egress fit |
+|---|---|---|---|---|---|---|
+| RHEL/Rocky/Alma 8.x | system Python usually too old for `~=3.10`; user env required | 2.28 | good for x86_64/aarch64 manylinux wheels | strong | technically okay, ops-limited | site-specific |
+| RHEL/Rocky/Alma 9.x | system Python 3.9 still below floor; user env required | 2.34 | good | strong | technically okay, ops-limited | site-specific |
+| Ubuntu 22.04 LTS | Python 3.10 meets floor | 2.35 | excellent | optional, not mandatory | good if terminal is sane | generally easiest |
+| Ubuntu 24.04 LTS | Python 3.12 exceeds floor | 2.39 | excellent | optional | best of the list | generally easiest |
+| SLES 15 SP5/SP6 | system Python not good enough by default; modules or user env required | SP5: effectively 2.31-ish / SP6: 2.38 | good | strong | okay in principle, but vendor-login policy matters | site-specific |
+| HPE Cray CLE/COS 16/17 class | site module Python usually required; stock system Python not enough | typically SLES 15 SP5/SP6 lineage | good once in user env | strongest option | weakest ops fit on shared login nodes | often restricted |
+| Debian 12 | Python 3.11 exceeds floor | 2.36 | excellent | optional | good | usually easy on smaller clusters |
+### 2.2 OS-by-OS notes
+#### RHEL / Rocky / Alma 8.x
+- GLIBC 2.28 is sufficient for the audited Python wheels in scope.
+- The problem is Python, not GLIBC.
+- Stock EL8 userland is typically centered on Python 3.6 or 3.9-era workflows,
+not Python 3.10+ as required by `pyproject.toml`.
+- If the site already offers:
+  - a Python 3.10+ module,
+  - Miniforge,
+  - micromamba,
+  - Spack python,
+then the agent stack is technically fine.
+- If the site insists on stock system Python only, the pipeline is a nonstarter.
+- Rocky 8 support runs to 2029-05-31, which means EL8-class login nodes will
+still exist for a while in tier-2 and tier-3 academic clusters. [W24]
+#### RHEL / Rocky / Alma 9.x
+- GLIBC 2.34 is comfortably above the manylinux_2_17 floor used by the key
+compiled wheels.
+- The same Python issue remains.
+- RHEL 9 class systems ship Python 3.9 by default more often than 3.10+.
+- So the pipeline still needs a user-managed Python stack.
+- Once that exists, EL9 is technically cleaner than EL8.
+- Rocky 9 support runs to 2032-05-31. [W24]
+#### Ubuntu 22.04 LTS
+- This is the first OS in the matrix where the default Python version actually
+satisfies the project floor.
+- GLIBC 2.35 is above every relevant wheel floor in this audit.
+- On departmental clusters and research workstations, Ubuntu 22.04 is a clean
+target.
+- On shared university login nodes, policy and network still matter, but the OS
+itself is not the blocker.
+- Ubuntu 22.04 standard LTS support runs until April 2027. [W18]
+#### Ubuntu 24.04 LTS
+- Best technical fit of the list.
+- Python 3.12 is comfortably above the requirement.
+- GLIBC 2.39 removes any ambiguity for manylinux_2_17 and most newer wheel
+tags.
+- If I were deploying this pipeline on a self-managed lab gateway node, this is
+the path of least resistance.
+- Ubuntu 24.04 standard LTS support runs until 2029-05-31. [W19]
+#### SLES 15 SP5 / SP6
+- SLES 15 major-line lifecycle is long, but service-pack support is rolling,
+with the previous SP supported for six months after the next SP release. [W25]
+- SLES 15 also warns against swapping out the system Python; use an explicit
+virtual environment or non-system Python. [W17]
+- SP6 clearly documents `glibc` 2.38. [W16]
+- SP5 sources reviewed here do not expose a one-line public GLIBC statement the
+way SP6 does; operationally I treat SP5 as SLE15-era ABI territory and flag it as
+older-than-SP6, not as unsupported.
+- For HPC front ends based on SLES, the real path is almost always:
+  - site Python module,
+  - Miniforge/micromamba,
+  - or a site-supported Apptainer/Singularity image.
+#### HPE Cray CLE / COS 16 / 17 class systems
+- On named systems, the user-facing reality is a SLES-backed Cray OS / COS
+stack, not a generic distro you control.
+- NERSC Perlmutter moved to COS 3.1 (SLES 15 SP5) in February 2025 and COS 3.3
+(SLES 15 SP6) in February 2026. [W14]
+- OLCF Frontier documents Cray OS 2.4 based on SLES 15.4 and later notes an
+upgrade to Cray OS 3.0 on SLES 15 SP5. [W9]
+- These systems are ABI-capable once you are inside a modern user Python.
+- They are not culturally or operationally friendly to “leave a full-screen AI
+agent on the login node and see what happens”.
+#### Debian 12
+- Debian 12 is technically very clean for this stack.
+- Python 3.11 satisfies the floor.
+- GLIBC 2.36 is comfortably modern.
+- Debian 12 full support runs to 2026-06-10 and LTS to 2028-06-30. [W23]
+- This is less common in national-lab front ends, but common enough in smaller
+institutional clusters and lab-owned gateways.
+### 2.3 Named-site examples relevant to the matrix
+- NERSC Perlmutter:
+  - HPE Cray EX platform
+  - uses Lmod
+  - login nodes have cgroup limits
+  - current OS timeline shows COS 3.3 on SLES 15 SP6 in February 2026. [W14]
+- OLCF Frontier:
+  - Cray EX / Cray OS lineage
+  - docs explicitly say long-running compute belongs on compute nodes
+  - login node misuse may be killed without warning. [W9]
+- TACC Frontera / Stampede class systems:
+  - docs now explicitly warn that AI-assisted tasks should run on compute nodes
+obtained via `idev`. [W7] [W8]
+## 3. GLIBC Version Drift
+### 3.1 Short answer
+GLIBC drift is **not** the dominant blocker for the audited pipeline on the OSes in
+scope.
+The audited stack is mostly aligned with mainstream manylinux wheels.
+### 3.2 Key wheel floors from fetched metadata
+- `pydantic-core` publishes x86_64 Linux wheels tagged
+`manylinux_2_17_x86_64`. [W11]
+- `numpy 1.26.4` publishes x86_64 wheels tagged
+`manylinux_2_17_x86_64`. [W13]
+- `scipy 1.15.2` publishes x86_64 wheels tagged
+`manylinux_2_17_x86_64`. [W12]
+- `PyYAML 6.0.3` publishes manylinux wheels for CPython 3.10. [W22]
+- `watchdog` publishes manylinux2014 wheels. [W21]
+- `textual` is `py3-none-any`; GLIBC is irrelevant for Textual itself. [W15]
+- `ase 3.24.0` is `py3-none-any`; its native dependency burden is inherited
+through `numpy` and `scipy`, not ASE itself. [W20]
+### 3.3 What that means for each OS family
+#### EL8 / Rocky 8 / Alma 8
+- GLIBC 2.28 is above the manylinux_2_17 floor.
+- So `numpy`, `scipy`, `pydantic-core`, `PyYAML`, and `watchdog` wheels are not
+blocked by GLIBC alone.
+- This is a major difference from old CentOS 7 / RHEL 7 environments, where the
+Python floor and wheel floor would both have hurt.
+#### EL9 / Rocky 9 / Alma 9
+- GLIBC 2.34 is above every wheel floor in this audit.
+- No GLIBC problem expected.
+- Again, the issue is Python 3.10+, not libc.
+#### Ubuntu 22.04 / 24.04 / Debian 12
+- All comfortably above the manylinux_2_17 floor.
+- Pure wheel path should be routine.
+- If builds happen from source, it is because of egress, wheel mirror, or tool
+policy, not because of GLIBC age.
+#### SLES 15 SP5 / SP6
+- SP6 explicitly updates `glibc` to 2.38. [W16]
+- SP5 is older, but still modern enough for the wheel floors in this stack.
+- In practice, SP5/SP6-class systems are fine once you are in a modern Python
+environment.
+#### Cray COS / CLE systems
+- Perlmutter on COS 3.1 / 3.3 and Frontier on Cray OS 2.4 -> 3.0 show the same
+pattern: front-end ABI age is not the problem. [W9] [W14]
+- The pain points are user-environment bootstrap, site policy, and outbound
+network.
+### 3.4 pydantic-core specifics
+- `pydantic` itself is pure Python.
+- `pydantic-core` is the compiled Rust extension that matters.
+- Current x86_64 manylinux wheels are tagged at GLIBC 2.17+. [W11]
+- That means all OSes in scope can load the wheel.
+- If you do not get a wheel, local Rust toolchain requirements become an HPC
+support problem very quickly.
+- This is why I would avoid “build from source on the login node” strategies.
+### 3.5 Textual specifics
+- Textual is pure Python and not GLIBC-sensitive itself. [W15] [W5]
+- Its problem domain is terminal behavior, not libc.
+- Mouse support, truecolor behavior, box drawing, UTF-8, and remote SSH/tmux
+behavior matter more than GLIBC.
+### 3.6 ASE specifics
+- ASE is pure Python. [W20]
+- The native bits arrive through `numpy` and `scipy`.
+- Therefore, “ASE on older RHEL” is really “NumPy/SciPy wheel availability on
+that Python + arch + mirror”.
+### 3.7 Real drift risk not captured by GLIBC alone
+The real drift risk is the intersection of:
+- old site Python
+- new package resolver choices
+- incomplete wheel mirrors
+- restricted outbound HTTPS
+- login nodes without compilers or Rust toolchains
+That is why EL8/EL9/SLES15 can be ABI-safe but still operationally awkward.
+### 3.8 GLIBC verdict
+- In-scope OSes: mostly fine.
+- Out-of-scope legacy CentOS 7 / RHEL 7: likely painful.
+- For this audit target, GLIBC is an amber footnote, not the top finding.
+## 4. Login-node Constraints
+### 4.1 General HPC reading of the pipeline
+The pipeline has three very different behavior classes.
+1. light login-node-safe behaviors.
+   - `doctor` ping only
+   - method recommendation
+   - dry input generation
+   - session metadata writes
+2. gray-zone behaviors.
+   - full-screen TUI left running for hours
+   - frequent file watching / polling
+   - repeated remote API calls
+3. bad login-node behaviors.
+   - `run_local` for Gaussian / ORCA
+   - anything threaded or CPU-heavy
+   - large local file parsing over shared filesystems
+   - “agent loops” left unattended on a crowded shared front end
+### 4.2 NERSC Perlmutter
+NERSC is explicit.
+- Perlmutter login nodes are subject to Linux cgroup limits. [W10]
+- Per-user limits documented in the fetched source are:
+  - 30 GB memory
+  - 12.5% CPU
+- NERSC says small, short interactive tasks can run there.
+- NERSC says extended runtimes or large datasets should go to batch QOSes.
+[W10]
+Operational reading:
+- `chemsmart agent doctor`:
+  - acceptable
+- `chemsmart agent run --dry-submit` for a short request:
+  - probably acceptable
+- full-screen TUI all afternoon on the login node:
+  - poor citizenship
+- `run_local` invoking Gaussian/ORCA on the login node:
+  - absolutely the wrong move
+### 4.3 TACC Frontera / Stampede class systems
+TACC has tightened AI guidance.
+- TACC Good Conduct now says users are responsible for AI-launched processes.
+[W7]
+- The suggested workflow is:
+  - acquire compute nodes with `idev`
+  - then connect the AI tool to the allocated compute node(s). [W7]
+- Stampede docs already say not to run applications on login nodes and to use
+`idev` for interactive work. [W8]
+- Frontera docs now strongly recommend that AI-assisted tasks run on compute
+nodes. [W8]
+Operational reading:
+- leaving the agent TUI on a TACC login node is not how they want users to run
+AI clients.
+- if the user wants this workflow at TACC, the right operational pattern is:
+  - `idev`
+  - shell or tmux inside the compute allocation
+  - then run the agent there
+- that is a deployment note, not a code change.
+### 4.4 OLCF Frontier
+OLCF is equally clear.
+- Frontier says login nodes are for edit/compile/manage/submit work. [W9]
+- Frontier says long-running computational tasks belong on compute nodes. [W9]
+- Frontier warns compute-intensive, memory-intensive, or otherwise disruptive
+processes on login nodes may be killed without warning. [W6]
+Operational reading:
+- `run_local` on Frontier login nodes is an AUP risk.
+- a long-lived Textual agent loop is also risky if it polls, tails, or makes
+repeated network calls for extended periods.
+- use `srun` / batch-interactive / dedicated compute time instead.
+### 4.5 Why `run_local` is especially problematic
+`run_local(job)` does not just ping an API.
+It can invoke the real chemistry code path.
+That means:
+- local scratch use
+- local stdout/stderr growth
+- CPU and memory burn
+- potential license-server chatter
+- program-specific startup scripts and modules
+On a national-lab login node that is exactly the class of behavior that gets users
+contacted by operations or outright throttled.
+### 4.6 Why even dry-submit TUI sessions can still annoy admins
+Even dry-submit mode can be noisy because it may:
+- keep a Textual full-screen session open
+- watch files via `watchdog`
+- poll session logs
+- hit external API gateways repeatedly
+- write many small artifacts in `~/.chemsmart/agent/sessions`
+None of those is catastrophic.
+All of them together are still not what login nodes are provisioned for.
+### 4.7 Login-node constraints verdict
+- Short advisory or dry-submit use: usually okay.
+- Long-running TUI use on shared login nodes: amber to red.
+- `run_local` on login nodes: red.
+- Best practice at major centers:
+  - launch from an interactive compute allocation,
+  - or confine login-node use to short planning / submit-only tasks.
+## 5. Network Egress
+### 5.1 What the code actually contacts
+The audited provider code uses SDKs, but the configured network target is not the public
+OpenAI or Anthropic endpoint.
+It points both providers at:
+- `https://factchat-cloud.mindlogic.ai/v1/gateway`
+- `https://factchat-cloud.mindlogic.ai/v1/gateway/claude`
+So for this exact audited code path:
+- direct `api.openai.com` reachability is not required by the code
+- direct `api.anthropic.com` reachability is not required by the code
+- outbound HTTPS to `factchat-cloud.mindlogic.ai` is required
+That is a very important HPC deployment detail.
+### 5.2 Why this matters on clusters
+HPC network policy is usually split by node role.
+Common pattern:
+- login nodes:
+  - outbound HTTPS often allowed, sometimes proxied, sometimes rate-limited
+- compute nodes:
+  - outbound internet sometimes blocked outright
+  - or restricted to mirrors, license servers, and center services
+- DTNs:
+  - intended for bulk transfer, not interactive API chat loops
+NERSC, for example, exposes dedicated DTNs for wide-area transfers rather than treating
+login nodes as bulk transfer workhorses. [W4]
+### 5.3 Named-site implications
+#### NERSC
+- NERSC explicitly separates DTNs for WAN transfer use. [W4]
+- NERSC also documents that some institutions themselves operate allowlists for
+outbound/inbound connectivity. [W18]
+- Translation for this pipeline:
+  - if `factchat-cloud.mindlogic.ai` is not reachable from the login node, the
+agent is dead on arrival.
+  - if compute nodes lack egress, a TACC-style or OLCF-style “run it inside a
+compute allocation” workflow only works if the site also permits HTTPS from those nodes.
+#### TACC
+- TACC's AI guidance pushes AI tools toward compute allocations. [W7] [W8]
+- That only helps if the compute allocation can still reach the required HTTPS
+endpoint.
+- In practice this has to be validated site by site.
+#### OLCF
+- OLCF has segregated environments like SPI with explicit IP allowlisting. [W6]
+- That is a reminder that some ORNL-adjacent environments are deliberately not
+open egress zones.
+- If the user wants this pipeline in a protected enclave or restricted project
+space, assume no-go until proven otherwise.
+### 5.4 Proxy and SOCKS considerations
+The chemsmart code itself does not implement proxy handling.
+So any proxy behavior would have to come from the underlying SDK / HTTP stack and site
+environment.
+Operationally I would state it like this:
+- explicit chemsmart proxy support:
+  - none observed in the audited code
+- possible SDK-level proxying:
+  - plausible through the underlying HTTP client stack
+  - but not guaranteed by chemsmart itself
+- SOCKS-only environments:
+  - validate manually before assuming success
+- air-gapped enclaves:
+  - no-go unless the gateway is mirrored internally
+### 5.5 Package-install egress versus runtime egress
+There are two separate egress problems.
+1. bootstrap egress. - PyPI / conda-forge / wheel mirror access 2. runtime egress. -
+HTTPS to the mindlogic gateway
+A site may allow one and not the other.
+Examples:
+- package mirrors available internally, but no public API egress
+- login node internet allowed, but compute node internet blocked
+- PyPI reachable only through a proxy, while custom gateways are blocked
+### 5.6 Network verdict
+- If `factchat-cloud.mindlogic.ai` on port 443 is blocked, the agent pipeline is
+functionally dead.
+- If the site allows only proxied egress, test `doctor` first.
+- If the target environment is an air-gapped, export-controlled, or SPI-style
+enclave, assume no-go until networking is explicitly designed for it.
+## 6. Terminal/TUI Rendering
+### 6.1 What the code expects
+The TUI is built on Textual.
+The audited TUI code uses:
+- full-screen app behavior
+- stylesheets
+- bindings
+- mouse in normal mode
+- file watching
+- log tailing
+- styled header text with a Unicode middot wordmark
+Textual itself says Linux distros can run Textual apps in terminal emulators, and it
+also says Textual apps can run remotely over SSH. [W5] [W20]
+### 6.2 What the code does to soften terminal problems
+There is a real fallback path in the audited code.
+`chemsmart agent --plain` does all of the following:
+- disables animation
+- runs inline
+- avoids screen clear behavior
+- turns mouse off
+- switches the header wordmark from `chem · smart` to `CHEMSMART`
+That matters a lot on conservative terminals and older tmux setups.
+### 6.3 Color depth and glyph expectations
+Textual docs note that some terminals are limited to 256 colors and that box characters
+may render poorly in weaker terminals. [W5] [W26]
+Operational expectation for this app:
+- best case:
+  - UTF-8 terminal
+  - 256 colors or better
+  - mouse support
+  - sane alternate-screen behavior
+- acceptable fallback:
+  - UTF-8 terminal
+  - `--plain`
+  - no mouse
+  - inline rendering
+- bad case:
+  - `TERM=dumb`
+  - non-UTF-8 locale
+  - broken box drawing
+  - SSH client that eats modifier keys or mouse sequences
+### 6.4 tmux reentrance
+This is an HPC operations issue more than a code issue.
+On clusters, users will naturally run this inside `tmux`.
+Expected good practice:
+- outer terminal should be UTF-8 and at least 256-color capable
+- `tmux` should advertise `tmux-256color` or `screen-256color`
+- use `--plain` first if display glitches appear
+- do not rely on mouse until basic redraw and keyboard handling are stable
+- reconnecting to the same `tmux` pane is safer than leaving a naked login-node
+TUI attached to a flaky SSH session
+I do not see explicit tmux-specific code in the audited tree.
+So tmux behavior is inherited from Textual + terminal + terminfo quality.
+### 6.5 Terminal clients in the real world
+Operationally, I would rank common SSH clients for this app like this:
+- WezTerm / Kitty / modern iTerm2 / Tabby:
+  - best chance of clean Textual behavior
+- MobaXterm:
+  - usually workable, but test `--plain` first
+- PuTTY:
+  - workable only if UTF-8 and 256-color settings are correct; mouse and box
+drawing are where I would expect the first complaints
+- browser-shell wrappers / institutional portals:
+  - highly variable; assume redraw quirks until proven otherwise
+This ranking is experience-based, not a statement from the chemsmart code.
+### 6.6 Clipboard behavior
+- Textual supports text selection in many widgets. [W26]
+- `pyperclip` on Linux typically depends on helper tools such as `xclip` or
+`xsel`, or a GUI clipboard path. [W27]
+- On a bare SSH login node with no X11 or clipboard helpers, clipboard features
+are unreliable.
+- That is not a blocker.
+- It just means users should rely on terminal copy mode rather than expecting a
+native desktop clipboard to exist.
+### 6.7 TUI verdict
+- Technically viable on modern terminals.
+- Best with `--plain` on shared HPC systems.
+- Full-screen mode is fine on clean UTF-8 256-color terminals, but I would not
+treat it as the default support path for conservative institutional SSH clients.
+## 7. Filesystem & Quota
+### 7.1 What the pipeline writes where
+Persistent config and session writes land under `~/.chemsmart`.
+That includes:
+- `~/.chemsmart/server/`
+- `~/.chemsmart/gaussian/`
+- `~/.chemsmart/orca/`
+- `~/.chemsmart/agent/sessions/<id>/`
+Working-directory writes include:
+- generated `.com` / `.gjf` / `.inp` files
+- submit scripts
+- run scripts
+- local stdout/stderr files
+- chemistry program outputs if `run_local` is used
+### 7.2 Metadata behavior matters more than bytes
+On Lustre and GPFS, many small files are usually a metadata problem before they become a
+capacity problem.
+The agent session structure creates many small artifacts:
+- `decision_log.jsonl`
+- `session.json`
+- `state.json`
+- `session_metadata.json`
+- per-step JSON artifacts
+One session is small.
+Hundreds of short sessions can still create noticeable metadata chatter on a busy home
+filesystem.
+### 7.3 Expected footprint
+Rough operational sizing:
+- static config in `~/.chemsmart`:
+  - tiny
+  - usually kilobytes to low megabytes
+- each dry-submit agent session:
+  - usually tens to hundreds of kilobytes
+- each long multi-turn session:
+  - can grow into low megabytes depending on logs and generated artifacts
+- chemistry outputs from real runs:
+  - dominate everything else
+  - can become gigabytes quickly depending on workflow
+### 7.4 Home quota concerns
+Typical shared-cluster home constraints:
+- limited space
+- strict inode/file-count sensitivity
+- backups or snapshots that make chatty logs more expensive than users realize
+That means:
+- short agent sessions under `~/.chemsmart/agent/sessions` are fine
+- long unpruned session histories are an avoidable nuisance
+- if the user turns this into a daily driver, session pruning becomes part of
+operations hygiene
+### 7.5 Scratch versus home tension
+The code defaults session state to `$HOME`, not `$SCRATCH`.
+That is operationally conservative in one sense:
+- session metadata survives node reboots and scratch purges
+But it is suboptimal in another:
+- home is where metadata pressure and quota complaints happen first
+For the chemistry outputs themselves:
+- scratch is still the right place for large program outputs
+- home is fine for agent metadata and small generated inputs
+### 7.6 Lustre / GPFS specifics
+#### Lustre
+- Great for large streaming I/O.
+- Bad place to spray endless tiny metadata updates if you can avoid it.
+- NERSC explicitly documents Lustre striping and performance tuning because the
+filesystem is built for scale, not careless small-file patterns. [W29]
+#### GPFS / Spectrum Scale
+- Similar operational rule.
+- Small-file storms hurt metadata and namespace operations more than raw bytes.
+### 7.7 Submit-script and working-directory considerations
+Because `submit_hpc` reconstructs submit scripts in the job folder, the user should keep
+the working directory on a filesystem that is:
+- visible from the submit context
+- visible from the eventual compute context
+- not absurdly expensive for small files
+On cross-mounted environments, this matters.
+A submit script created in one namespace and submitted from another is a common
+real-cluster failure mode.
+### 7.8 Filesystem verdict
+- Session metadata footprint: small but chatty.
+- Chemistry output footprint: potentially large.
+- Keep agent metadata in home, but prune it.
+- Keep heavy chemistry outputs and temporary files in the site's intended work
+or scratch location.
+## 8. Locale & Encoding
+### 8.1 Why locale matters here
+The audited code writes and reads UTF-8 in multiple places.
+Examples:
+- decision log JSONL files are opened with `encoding="utf-8"`
+- result artifacts are written as UTF-8 JSON
+- the styled wordmark uses a Unicode middot: `chem · smart`
+- Rich / Textual rendering frequently relies on Unicode box-drawing behavior
+### 8.2 POSIX `C` locale risk
+On older or minimal cluster images, users still occasionally land in:
+- `LANG=C`
+- `LC_ALL=C`
+- no UTF-8 locale exported in noninteractive shells
+Modern Python often softens that, but I do not recommend gambling on it.
+Operationally safe setting:
+```bash
+export LANG=en_US.UTF-8
+export LC_ALL=en_US.UTF-8
+```
+or the site-supported UTF-8 locale equivalent.
+### 8.3 What breaks first when locale is wrong
+Usually in this order:
+- wordmark punctuation or Unicode glyphs look wrong
+- box drawing degrades
+- selection / copy behavior becomes confusing
+- some logs or file previews render mojibake
+The chemistry inputs themselves are mostly ASCII-dominant.
+The TUI is where locale issues show up.
+### 8.4 Fallback behavior available in code
+The audited code already provides a useful fallback.
+`--plain` switches the header to ASCII `CHEMSMART`.
+That is a good emergency path when:
+- the locale is wrong
+- the terminal font lacks the middot or box glyphs
+- the client terminal is ancient
+### 8.5 Locale verdict
+- UTF-8 should be treated as a requirement for first-class TUI use.
+- ASCII-ish plain mode is an acceptable backup.
+- This is manageable, but it is another reason I would not market the default
+full-screen TUI as a drop-in fit for every institutional SSH client.
+## 9. Python Environment Strategy
+### 9.1 General rule
+Do **not** try to make this ride on stock system Python on shared HPC front ends.
+Use a user-managed environment.
+The right tool depends on the OS family and the site's egress model.
+### 9.2 EL8 / EL9 strategy
+Recommended order:
+1. site-provided Python 3.10+ module + venv 2. site-supported Miniforge / micromamba 3.
+user micromamba in `$HOME` 4. Spack, if the site already curates it well 5. `uv`, only
+if egress and binary bootstrap are uncomplicated
+Why I do **not** put `uv` first on EL clusters:
+- a lot of HPC sites do not let users casually pull the internet from every
+node role
+- some sites strip TLS inspection or proxy behavior in strange ways
+- wheel acquisition matters more than raw installer speed
+- micromamba is simply a more familiar support path for science users on EL
+clusters
+### 9.3 Ubuntu 22.04 / 24.04 strategy
+Recommended order:
+1. `python -m venv` + pip, if the site has clean egress or a mirror 2. `uv`, if the site
+likes modern Python tooling and outbound package fetches 3. micromamba, if the user
+already standardizes on conda-family stacks
+Ubuntu is where `uv` makes the most sense in this audit.
+### 9.4 Debian 12 strategy
+Same pattern as Ubuntu.
+Recommended order:
+1. venv + pip 2. `uv` 3. micromamba if mirrors or institutional practice favor it
+### 9.5 SLES 15 SP5 / SP6 strategy
+Recommended order:
+1. site Python module + venv 2. micromamba / Miniforge 3. Spack if the site already
+supports it 4. avoid touching system Python directly
+SUSE explicitly warns against changing the system Python interpreter. [W17]
+That aligns with normal HPC good practice anyway.
+### 9.6 HPE Cray COS / CLE strategy
+Recommended order:
+1. site-provided Python module if available 2. site-provided Miniforge / conda module if
+available 3. user micromamba under `$HOME` 4. Apptainer/Singularity image for the
+userland, if policy allows
+Why I would not lead with Spack here:
+- user-level Spack bootstraps on Cray front ends are not what most chemistry
+users want to debug
+- micromamba or a curated module is operationally cleaner
+- named sites already expose module ecosystems and, in Perlmutter's case,
+Miniforge modules in the public software stack. [W14]
+### 9.7 Conda versus uv versus Spack versus site module
+#### site module
+Pros:
+- lowest friction with center policy
+- admins can support it
+- best integration with scheduler, compilers, and filesystem expectations
+Cons:
+- not always new enough
+- may not include the exact Python minor version you want
+#### micromamba / conda
+Pros:
+- strongest cross-site story for science users
+- binary-first
+- easiest way around old system Python
+- familiar to most computational chemistry groups
+Cons:
+- can sprawl in `$HOME`
+- can become messy without pruning
+#### uv
+Pros:
+- fast
+- simple on modern Ubuntu/Debian
+- nice developer ergonomics
+Cons:
+- less friendly where egress is restricted or mirrors are incomplete
+- not the default support muscle-memory on many shared academic clusters
+#### Spack
+Pros:
+- great if the site already curates it
+- excellent for ABI-aware HPC software stacks
+Cons:
+- overkill for this agent stack from an end-user perspective
+- source builds can be slow and policy-unfriendly on login nodes
+### 9.8 Environment-strategy verdict
+- Best universal answer for this pipeline on HPC: micromamba or site Python
+module + venv.
+- Best answer on Ubuntu/Debian lab gateways: venv or `uv`.
+- Worst answer almost everywhere: stock system Python only.
+## 10. Per-OS Risk Summary
+| OS | Status | One-line rationale |
+|---|---|---|
+| RHEL/Rocky/Alma 8.x | AMBER | GLIBC is fine, but Python 3.10+ needs a user env and login-node AI/TUI use remains policy-sensitive. |
+| RHEL/Rocky/Alma 9.x | AMBER | Cleaner ABI than EL8, but stock Python is still too old and site egress/policy still dominate. |
+| Ubuntu 22.04 LTS | GO | Default Python meets the floor and wheel ABI is easy; remaining risks are policy and gateway reachability. |
+| Ubuntu 24.04 LTS | GO | Best technical fit in the matrix: modern Python, modern GLIBC, and easy wheel path. |
+| SLES 15 SP5 | AMBER | ABI is probably okay, but system Python is too old and SP5-era front ends are less comfortable than SP6. |
+| SLES 15 SP6 | AMBER | Modern enough technically, but still usually needs a user-managed Python and inherits shared-login-node policy limits. |
+| HPE Cray CLE/COS 16 class | AMBER | Works only if you use the site's Python/module path and avoid login-node misuse; not a casual drop-in. |
+| HPE Cray CLE/COS 17 class | AMBER | Same as above, but newer SLES/SP6 lineage makes the ABI side easier than the policy side. |
+| Debian 12 | GO | Python 3.11 and GLIBC 2.36 make this an easy technical target, especially on smaller institutional clusters. |
+### 10.1 Overall risk statement
+If “runs without issue” means:
+- no user-managed Python,
+- no network exceptions,
+- no terminal tuning,
+- no policy caveats,
+- and no packaging footguns,
+then the answer is **no** for every shared HPC login-node family in scope.
+If “runs without issue” means:
+- user is willing to create a supported Python 3.10+ environment,
+- login-node use is short and respectful,
+- outbound HTTPS is allowed,
+- and plain-mode TUI is acceptable,
+then Ubuntu 22.04+, Debian 12, EL8/EL9, and SLES15-class systems are all technically
+serviceable.
+## 11. Web Research Notes
+### 11.1 OS lifecycle and GLIBC sources
+- [W1] Textual getting started:
+  - https://textual.textualize.io/getting_started/
+- [W2] NERSC resource-usage policy:
+  - https://docs.nersc.gov/policies/resource-usage/
+- [W3] Red Hat lifecycle page:
+  - https://access.redhat.com/articles/4038291
+- [W4] Ubuntu 22.04 release notes:
+  - https://documentation.ubuntu.com/release-notes/22.04/
+- [W5] Ubuntu 24.04 release notes:
+  - https://documentation.ubuntu.com/release-notes/24.04/
+- [W6] SLES 15 SP6 release notes:
+  - https://documentation.suse.com/releasenotes/sles/15-SP6/index.html
+- [W7] Debian 12 package page for `libc6`:
+  - https://packages.debian.org/bookworm/libc6
+- [W8] AlmaLinux lifecycle / release notes:
+  - https://wiki.almalinux.org/release-notes/
+- [W9] Rocky Linux release and version guide:
+  - https://wiki.rockylinux.org/rocky/version/
+- [W10] RHEL 8.0 release notes with GLIBC 2.28 statement:
+  - https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/pdf/8.0_release_notes/80-release-notes.pdf
+- [W11] RHEL 9 package-manifest / support material used to confirm EL9 glibc
+2.34 lineage:
+  - https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/pdf/package_manifest/red_hat_enterprise_linux-9-package_manifest-en-us.pdf
+  - https://access.redhat.com/solutions/7087181
+- [W12] Debian 12 release information and support dates:
+  - https://www.debian.org/releases/bookworm/index
+- [W13] SLES 15 SP6 lifecycle statement:
+  - https://documentation.suse.com/sles/15-SP6/pdf/book-upgrade_en.pdf
+- [W14] SLES 15 SP6 / SP5 rolling-SP policy statement:
+  - https://documentation.suse.com/es-es/sles/15-SP6/html/SLES-all/cha-upgrade-background.html
+  - https://documentation.suse.com/releasenotes/legacy/sles/15-SP5/index.html
+### 11.2 Named-site OS and policy sources
+- [W15] OLCF Frontier user guide:
+  - https://docs.olcf.ornl.gov/systems/frontier_user_guide.html
+- [W16] NERSC Perlmutter timeline:
+  - https://docs.nersc.gov/systems/perlmutter/timeline/
+- [W17] NERSC Perlmutter architecture:
+  - https://docs.nersc.gov/systems/perlmutter/architecture/
+- [W18] NERSC connection guide / allowlist note:
+  - https://docs.nersc.gov/connect/
+- [W19] NERSC Lmod page:
+  - https://docs.nersc.gov/environment/lmod/
+- [W20] TACC Good Conduct guide:
+  - https://docs.tacc.utexas.edu/basics/conduct/
+- [W21] TACC Stampede2 archive docs for login-node / `idev` guidance:
+  - https://docs.tacc.utexas.edu/archives/hpc/stampede2/
+- [W22] TACC Frontera user guide:
+  - https://docs.tacc.utexas.edu/hpc/frontera/
+- [W23] TACC `idev` docs:
+  - https://docs.tacc.utexas.edu/software/idev/
+- [W24] OLCF SPI page for allowlisted/protected environments:
+  - https://docs.olcf.ornl.gov/spi/index.html
+- [W25] NERSC DTN page:
+  - https://docs.nersc.gov/systems/dtn/
+### 11.3 Package / wheel sources
+- [W26] `pydantic_core` PyPI page:
+  - https://pypi.org/project/pydantic_core/
+- [W27] `textual` PyPI page:
+  - https://pypi.org/project/textual/
+- [W28] `watchdog` PyPI page:
+  - https://pypi.org/project/watchdog/
+- [W29] `scipy 1.15.2` PyPI page:
+  - https://pypi.org/project/scipy/1.15.2/
+- [W30] `numpy 1.26.4` PyPI page:
+  - https://pypi.org/project/numpy/1.26.4/
+- [W31] `openai 1.92.2` PyPI page:
+  - https://pypi.org/project/openai/1.92.2/
+- [W32] `anthropic` PyPI page:
+  - https://pypi.org/project/anthropic/
+- [W33] `ase 3.24.0` PyPI page:
+  - https://pypi.org/project/ase/3.24.0/
+- [W34] `PyYAML` PyPI page:
+  - https://pypi.org/project/PyYAML/
+- [W35] `pyperclip` PyPI page:
+  - https://pypi.org/project/pyperclip/
+- [W36] `rich` PyPI page:
+  - https://pypi.org/project/rich/
+### 11.4 Top500 context sources
+- [W37] TOP500 statistics landing page:
+  - https://top500.org/statistics/
+- [W38] TOP500 project description:
+  - https://top500.org/project/top500_description/
+- [W39] historical TOP500 paper noting Linux takeover:
+  - https://www.top500.org/files/TOP500_Looking_back_HWM.pdf
+### 11.5 How I used the web sources
+- OS and lifecycle dates:
+  - [W3] [W4] [W5] [W8] [W9] [W12] [W13] [W14]
+- GLIBC cutoffs:
+  - [W6] [W7] [W10] [W11] [W30] [W29] [W26] [W34]
+- named-site policy / OS choices:
+  - [W15] [W16] [W17] [W18] [W19] [W20] [W21] [W22] [W23]
+- network / egress conventions:
+  - [W18] [W24] [W25]
+- TUI requirements:
+  - [W1] [W27] [W35] [W36]
+- package wheel behavior:
+  - [W26] [W27] [W28] [W29] [W30] [W31] [W32] [W33] [W34]
+## 12. Open Questions for the User
+1. Do you want the eventual deployment target to be: - only shared login nodes, - or
+login nodes plus interactive compute allocations? 2. Is the target environment expected
+to have outbound HTTPS to `factchat-cloud.mindlogic.ai`, or is it a restricted /
+allowlisted network? 3. Are you standardizing on: - site modules, - micromamba/conda, -
+Spack, - or containerized userlands? 4. Do you expect this to run on national-lab class
+systems only, or also on smaller university clusters where Ubuntu/Debian front ends are
+common? 5. Is a plain inline TUI acceptable as the supported mode on conservative
+terminals, or do you want full-screen Textual behavior to be a hard requirement? 6.
+Should the submit path assume: - local scheduler submission from the login node, - or an
+SSH hop to a distinct submit host? 7. Are you willing to treat direct `run_local` on
+login nodes as unsupported, and document compute-allocation use instead? 8. Is the audit
+consumer interested in “technical ABI compatibility only”, or in “works cleanly under
+real center policy without user workarounds”?
+## 13. Recommendation
+### 13.1 Verdict
+My verdict is:
+- **Technically compatible on modern Linux HPC OSes in scope**
+- **Operationally not login-node-clean without caveats**
+- **Overall rating: AMBER**
+If you deploy this as “short-lived planner / dry-submit tool on login nodes, preferably
+in `--plain` mode, with user-managed Python 3.10+ and confirmed HTTPS reachability”, it
+is serviceable.
+If you deploy this as “full-screen autonomous AI agent that may sit on shared login
+nodes, call external APIs repeatedly, and sometimes `run_local` real chemistry code”, it
+is not a good fit for NERSC/TACC/OLCF-class front ends.
+### 13.2 Per-OS deployment notes
+#### EL8 family
+- supported only with a user-managed Python 3.10+ environment
+- micromamba or site module preferred
+- do not rely on stock system Python
+#### EL9 family
+- same as EL8, but slightly cleaner ABI story
+- still not stock-Python-ready
+#### Ubuntu 22.04 / 24.04
+- easiest bare-metal or small-cluster targets
+- if this project ever needs a “reference gateway OS”, choose Ubuntu 24.04
+#### SLES 15 SP5 / SP6
+- workable via module or micromamba
+- be conservative about terminal support and locale
+- use plain mode first
+#### HPE Cray COS / CLE systems
+- prefer site module / site Miniforge
+- expect login-node policy scrutiny
+- prefer interactive compute allocations for anything beyond short dry-submit
+planning
+#### Debian 12
+- technically easy
+- likely strongest option for self-managed academic gateway nodes that are not
+bound to vendor HPC OS norms
+### 13.3 Highest-priority findings for decision-makers
+1. The stack is **not** blocked by GLIBC on the OSes in scope. 2. The stack **is**
+blocked by stock Python version on EL8, EL9, and SLES15. 3. The stack has a **broken
+documented credential path** because the code uses a hard-coded absolute `api.env` path.
+4. The stack has a **dependency declaration gap** because `rich` is imported but not
+declared directly. 5. The stack is a **policy mismatch** for long-lived
+shared-login-node AI/TUI use at major centers. 6. The stack is a **network-dependent
+service** because runtime success requires outbound HTTPS to the mindlogic gateway.
+### 13.4 Practical deployment guidance
+If the goal is to make this workable across common HPC sites without changing the
+codebase right now, I would advise users to do the following:
+- use a user-owned Python 3.10+ environment
+- export `ai_api_key` in the shell directly instead of relying on the README's
+`api.env` flow
+- verify outbound HTTPS to `factchat-cloud.mindlogic.ai` with a short doctor
+run
+- use `chemsmart agent --plain` as the first-line supported interface on HPC
+- treat login-node use as short planning / submit-only work
+- treat `run_local` on shared login nodes as unsupported practice
+- on TACC / OLCF / similar centers, move real interactive agent use into an
+interactive compute allocation
+### 13.5 Final answer to the stated question
+Does the `chemsmart` multi-tool agent pipeline at `20cbcdb9` run without issue on common
+HPC login-node OSes?
+- **No, not without issue.**
+- **Yes, with caveats, on most modern Linux OS families in scope.**
+- The caveats are dominated by Python environment management, credential-path
+portability, site network egress, terminal conservatism, and login-node policy, not by
+GLIBC.