initial load of the knowledge transfer layer and the transcript

# bl4b-alignment-integration instructions

This project contains correspondence, screenshots and log files developed during the course

of development of scripts and to automate sample alignment using the instrument control system.

You may read any and all files that are in this folder and which are provided in the /home/controls/**.

There are also files that may be referenced from the read-only experiment filesystem mounts at /SNS/REF_L/**.

You may use the ORNL intranet freely to research specifications and documentation. If there is information

that you require that references the public internet and are blocked from access, ask for help to obtain the file.

## Capabilites and Role

You are an EPICS automation specialist who is expert at Python. You are familiar with both pyepics and pydevice uses,

as well as EPICS database record syntax, and have a deep understanding of scan server and scantools modules used at the ORNL instrument suite.

You are able to direct agent teams who are system programmers and software developers who are also expert at using Phoebus (the UI system) and how to diagnose and fix memory, concurrency and file system errors.

## Problem specific files

There are many files that have been collected during previous investigations. These are noted in the following files and folders:

* /SNS/users/6ov/BL4B/2026/02/07/

* /SNS/users/6ov/BL4B/2026/03/26/

* /home/controls/var/tmp/ScriptScan/2026A/

* /home/controls/var/tmp/ScriptScan/scripts/

* /home/controls/var/tmp/PYTHON/2025-B/

* /home/controls/var/tmp/PYTHON/2026-A/

## Secure Temporary Files

When a task requires writing a temporary script or data file (e.g. to work around

shell quoting limits when calling an API), **never write it to a world-readable

path**.  `/tmp` on a multi-user Linux system is mode 1777 — files created there

with default umask are readable by every local user.

**Always create temporary files with mode 600 (owner read/write only):**

```python

import os, tempfile

# Preferred: tempfile.NamedTemporaryFile — mode 600 by default

with tempfile.NamedTemporaryFile('w', suffix='.py', delete=False) as fh:

    fh.write(script_content)

    tmp_path = fh.name

try:

    # use tmp_path ...

finally:

    os.unlink(tmp_path)   # always clean up

```

Or with the Write tool followed by an immediate chmod:

```bash

# After writing the file, restrict permissions immediately

chmod 600 /path/to/tempfile

```

**Additional rules:**

- Never embed credentials (tokens, passwords, keys) in files under `plan/`,

  `tests/`, or any other committed path.  Use environment variables or

  `~/.netrc` / `~/.config` files (also mode 600) instead.

- Delete temporary files as soon as they are no longer needed — use a

  `try/finally` block or the `delete=True` default of `NamedTemporaryFile`.

- If a script must be written to `/tmp` via the Write tool (which cannot set

  permissions atomically), run `chmod 600 <path>` in the very next Bash call

  before the file is used.

### Test data for development

Files in `/SNS/REF_L/` and `/SNS/users/6ov/` are accessed via sshfs mounts with cache. See the

parent project's `CLAUDE.md` for network mount handling rules.

**Do not revert the `read_only` parameter** — the production mount is `-o ro` and tests

will fail with `OSError: [Errno 30] Read-only file system` without it.

# bl4b-alignment-integration

Using the [Claude](https://code.ornl.gov/6ov/claude) agentic-engineering knowledge transfer workflow, I gathered information regarding the integration of Spyder scripts at BL4b into the scantools module. This is a module that uses several python modules, two IOCs and CSS UIs to generate scans that are processed by the scan server. The challenge ( *as described in [Redmine 4850](https://idac.ornl.gov/issues/4850)* ) is that integration into the existing workflow requires adjustment to several codes and IOCs.

As is my custom, I collect files and screenshots in my home folder on the DAQ/Analysis unified autohome folder mount, at the systematic path `${HOME}/${BL}/YYYY/MM/DD/*`. The agent runs on a machine that has the `/SNS/REF_L/` and `/SNS/users/${USER}/` mounted via an sshfs filesystem mount ( *which is setup easily by the workflow via `setup/mount-sshfs.sh`* ). The [architecture](https://code.ornl.gov/6ov/claude/-/blob/main/setup/docs/architecture.md?ref_type=heads) of this workflow and how knowledge transfers is documented.

## Progress on 2026-03-31

I spent time integrating into [bl4b:issue/4850](https://code.ornl.gov/idac/cs/legacy/bl4b/-/tree/issue/4850) and [scantools:issue/4850](https://code.ornl.gov/idac/cs/common/scantools/-/tree/issue/4850). I got pretty far, in so much as I could select 'xy' or 'xprofile' as the detector, choose 'chis' as the motor and the scan would invoke the alternate handling required to compute the needed statistics. There are some discrepancies, however, that prevent it from being ready to use in production.

## Progress on 2026-04-06

Under this environment, I created an initial [commit](TBD) to prepare for this investigation, based on previous work and an understanding of how to prompt the AI assistant to produce high quality results. From that step, I engaged in a the dialog that is captured below:

## Prompt 1

You are working in the tasking project, bl4b-alignment-integration branch. The code uses the Experimental Physics Industrial Control System (EPICS) as its basis. The task is to analyze the implementation of the 'chis' motor scan enhancements. These enhancements are present in the `/home/controls/bl4b` folder, issue/4850 branch, and `/home/controls/common/scantools/issue/4850/` folder (scantools issue/4850 branch). Please read any git log that are appropriate. The effort is a work in progress to integrate the function of the Spyder environment scripts that are contained in `/home/controls/var/tmp/PYTHON/2026-A/*`. First with the `CHI_scan.py` script, and then progressing onward `startup/Solid_theta_alignment_low_angle_2gauss.py` under the same model. Work done in 3/31 to 4/1 made some progress. There are some observed discrepancies. I would like you to perform a thorough review of the code to gain an understanding of how the various pieces fit together. Please produce a document that explains in full detail your understanding of the project in a way that can be given to future agents to perform a series of tasks. You and I will iterate on this document until we are both satisfied that it captures the full scope of how the instrument automation performs such alignment scanning. This is a cruical step because a lot of work is planned to improve this mechanism and a good foundational understanding of the process is key. If you need a tool to analyze the code or artifacts so far, please install it yourself according to the instructions in the cross-project layer (use pixi or uv with venv). If you are missing a log file or piece of information, please ask me to fetch it for you. If you run into an issue where you need sudo, ask me to execute the line in a separate terminal.