cloverleaf-larry/agents/cloverleaf-cheatsheet.md

Cloverleaf Operations — v3 Native Capability Reference

Larry-Anywhere v3 is self-contained. It does not invoke v1 bash scripts (tbn, hlq, mr, mp, mg, awkcut, each_site, etc.) and it does not invoke v2 cloverleaf-tools.pyz. Those layers can be present on a host; v3 ignores them.

Two kinds of capability:

1. Native tools — implemented in pure bash+awk under $LARRY_HOME/lib/, callable as first-class Anthropic-style tools (no bash_exec Y/N).
2. Cloverleaf product binaries — the binaries shipped with Cloverleaf itself ($HCIROOT/bin/, $HCIROOT/server/bin/, tclsh + Cloverleaf TCL libraries). These ARE part of Cloverleaf, not v1/v2. v3 invokes them directly via bash_exec (Y/N) when an operation requires the engine.

What Larry has natively (Anthropic tools)

NetConfig analysis — read

tool	use for
nc_list_protocols(netconfig)	"what threads are in this site?" — one name per line
nc_list_processes(netconfig)	"what processes are defined?"
nc_protocol_block(netconfig, name)	"show me the full definition of thread X"
nc_protocol_field(netconfig, name, field)	top-level field (PROCESSNAME, OBWORKASIB, OUTBOUNDONLY, GROUPS, ENCODING, ICLSERVERPORT, AUTOSTART, HOSTDOWN)
nc_protocol_nested(netconfig, name, path)	nested field via dotted path. Use this for HOST/PORT/TYPE/ISSERVER — those live in the inner PROTOCOL{} block. e.g. path=PROTOCOL.PORT
nc_protocol_summary(netconfig, [filter])	one-line TSV per protocol with direction, port, host, type — your default "lay of the land" call
nc_destinations(netconfig, name)	"what does this thread route to?" — unique DEST list from DATAXLATE. ONE HOP only — for the full multi-hop chain use nc_paths.
nc_sources(netconfig, name)	"what routes INTO this thread?" — unique source list. ONE HOP only — for the full chain use nc_paths.
nc_paths(thread, site, [all], [site_only])	"trace the FULL route chain / what feeds X / the whole path / downstream + upstream" — deterministic DFS path enumerator, output SITE THREAD HOPS PATH. Intra-site hops follow DATAXLATE DEST; cross-site links are via named destination blocks (a DEST naming a destination block resolves to its { SITE } { THREAD }; the PORT corroborates). The whole route graph is parsed once into memory and walked with O(1) lookups. For --up, THREAD = feeder ROOT and the queried thread is the terminus. Use this instead of repeated nc_destinations/nc_sources, grep, or read_file for ANY path / chain / route-tracing question.
nc_xlate_refs(netconfig, [name])	"what .xlt files are referenced?" — all or scoped to one protocol
nc_find_inbound(netconfig, mode, format)	"which threads are inbound?" — modes: tcp-listen (real upstream-client listeners, ISSERVER=1), icl-or-file (OBWORKASIB=1 internal mux/file inbounds), all. formats: tsv, jsonl, table
nc_document(thread | name, [site], [out])	"document this interface / system end-to-end" — emits the Legacy "ADT Messages" markdown template (Title, Description, Message Flow table Platform|Action|Description|From|To, per-delivery breakdown) for ONE interface (thread, e.g. ADTto_CodaMetrix) or a whole SYSTEM (name pattern, e.g. codametrix → one section per matching delivery thread across sites). Deterministic, pure bash, API-FREE (runs on API-blocked boxes). ★ For every referenced UPOC proc it surfaces the proc's comments, HL7 fields, matched event codes, table lookups, and disposition into the Description, and includes the raw proc TCL in a ## Referenced proc source appendix. When you get this output WITH the API, polish those surfaced UPOC bits into smooth filter prose in the Description — do NOT invent facts, just smooth what's surfaced. On an API-blocked host the deterministic bits + appendix ARE the deliverable (no "summarize by hand" marker).

NetConfig modification — generate, then write via write_file (Y/N gated)

tool

use for

nc_make_jump(netconfig, inbound, new_host, jump_port, [process_old], [process_new], [encoding])

Generate the jump threads for cross-env data replay (tag = the inbound thread name). Emits THREE threads + one route-add: linux_<tag>_out (OLD-side outbound tcpip-client, same process as the original inbound), windows_<tag>_in (NEW-side server_jump inbound tcpip-server listening on jump_port), windows_<tag>_out (NEW-side server_jump outbound that re-injects into NEW's existing inbound), AND the route-add snippet to splice into the OLD inbound's DATAXLATE. Generation only — does not modify any file. Larry uses write_file to actually persist, which goes through Y/N.

When Larry needs to add the OLD-side jump block to an existing NetConfig, the pattern is:

1. nc_make_jump(...) → captures full text
2. nc_protocol_block(netconfig, inbound) → finds the inbound's existing block + line range
3. read_file(netconfig) → loads the whole file
4. Splice (in Larry's head): insert new block + route-add into the right spots
5. write_file(netconfig, new_content) → Y/N preview shows the unified diff

What Larry invokes from Cloverleaf product binaries (via bash_exec, Y/N)

These are shipped with Cloverleaf. v3 invokes them directly — no v1 wrapper between.

operation	binary or command
dump a smat database to text	$HCIROOT/bin/hcidbdump <smat_file> or the equivalent that ships with this Cloverleaf version
start/stop/restart an engine site	$HCIROOT/bin/hcienginestop, hcienginerun, hcienginerestart (already wrappers — read them once with read_file to see what they actually call)
run a TCL test/route	tclsh with $HCIROOT/tcl/lib/cloverleaf/... libraries on the auto-path. The msi* family (msiAttach, msiGetStatSample, etc.) is the Cloverleaf TCL API for smat/route access.
engine connection status	hciconndump or via TCL msi* calls
check the netconfig is loadable	Use tclsh to source it; engine will report parse errors

When Larry doesn't know which binary fits an operation, the protocol is:

1. list_dir("$HCIROOT/bin") and list_dir("$HCIROOT/server/bin") to enumerate.
2. read_file on any wrapper script that looks relevant.
3. Propose the exact bash_exec command to Bryan with a # why: comment.

NetConfig structural cheat-sheet

A site's NetConfig is TCL-style nested blocks. Top-level:

• process <name> { ... } — a process container (usually 5–15 per site).
• protocol <name> { ... } — a thread (the operational unit). Each protocol has:
  • Top-level fields: PROCESSNAME, OUTBOUNDONLY, OBWORKASIB, GROUPS, ENCODING, ICLSERVERPORT, AUTOSTART, HOSTDOWN, KEEPMSGONDISK, etc.
  • Inner PROTOCOL { ... } block: TYPE (tcpip / pdl-tcpip / file), HOST, PORT, ISSERVER (0=client, 1=listener), LOCAL_IP, MLP_MODE, etc.
  • DATAXLATE { ... } block: the routing rules. Each route is { TRXID <regex> } { WILDCARD ON } { ROUTE_DETAILS { { DEST <thread> } { XLATE <.xlt> } { PROCS ... } { TYPE xlate|raw|generate } } }.
  • RECVCONTROL, SAVECONTROL, TPS_INBOUND, TPS_OUTBOUND — proc bindings.

Direction inference (canonical)

Use nc_find_inbound rather than rolling this yourself, but for reference:

if …	direction
PROTOCOL.ISSERVER == 1	inbound-tcp-listen — accepts upstream client TCP connections (e.g. listens for Epic). This is what Bryan means by "fed directly by upstream client systems."
OBWORKASIB == 1 (and ISSERVER != 1)	inbound-icl-or-file — receives via Cloverleaf inter-cloverleaf link (ICLSERVERPORT is set) or file drop. Usually TYPE=file.
OUTBOUNDONLY == 1	outbound — TCP client pushing data to an external system. HOST and PORT give the target.
none of the above	bidirectional / undefined — rare; investigate.

The jump-thread pattern (Example 1)

For each inbound thread T_in on the OLD env, you want:

1. On OLD — modify NetConfig:
   • Add a new outbound protocol linux_<T_in>_out (tcpip-client, points at the new linux host:jump_port).
   • Add a route to T_in's DATAXLATE block routing to that new outbound (TRXID .*, type raw, no xlate).
2. On NEW — modify the server_jump site's NetConfig:
   • Add a new inbound protocol windows_<T_in>_in (tcpip-server listening on the jump_port, OBWORKASIB=1).
   • Add a new outbound protocol windows_<T_in>_out (re-injects into NEW's existing inbound on 127.0.0.1:orig_port).
   • windows_<T_in>_in's DATAXLATE has one route: TRXID .* → DEST windows_<T_in>_out, type raw, no xlate.

Net result: data hitting T_in on OLD also flows to NEW via TCP, lands in windows_<T_in>_in, is forwarded by windows_<T_in>_out into NEW's existing T_in, and follows NEW's normal downstream routing — letting Bryan validate the cloned environment with live OLD data. (The tag in each generated name is the OLD inbound thread name.)

Use nc_make_jump for the generation. Use write_file (Y/N) for the persistence.

What this doc replaces

This replaces the earlier v0.2 cheat-sheet that listed v1 commands like tbn, tbp, hlq, mr, mp, mg, hl, etc. v3 doesn't call those. When a user asks something like "find ADT threads," Larry uses nc_find_inbound or nc_protocol_summary --filter ADT, not tbn ADT. The end-user value is the same; the implementation is owned by v3.