docs: sync with repo — CTE chimod chain, env vars, default compose

[lukemartinlogan]

Compared the docs against the current state of iowarp/clio-core and fixed what had drifted.

New page: Cache / Replication / Indexing ChiMods

docs/sdk/context-transfer-engine/chimod-chain.md documents the CTE interposition chain:

cache(563.0) → indexer(564.0) → [compressor(562.0) →] replication(561.0) → core(512.0)

It explains what an interposer is — a pool that speaks the CTE core's own method ids and task structs, overrides a handful of data verbs, and forwards everything else to next_pool_id, so a plain clio::cte::core::Client works unchanged — and then each layer:

• Replication — write-through to a fixed REPLICA_FIXED | REPLICA_PERSISTENT set, the async sweep (replicate_period_ms, 0 = synchronous), replica-served reads with primary re-cache, replica_score doubling as the drop threshold, plus ReplicateBlob / FlushTag.
• Cache — why the copy is stored raw (it's what keeps the zero-IPC SHM read path alive for compressed blobs), writer-local routing, the write-local-then-register coherence protocol, speculative-copy verification, why the owner node deliberately keeps no copy, and min_score as a score floor.
• Indexer — indexing is off the ack path (O(1) coalesced enqueue), sweep vs. lazy, the read-your-writes drain before every search, BM25 over the matched slice only, snapshot+WAL persistence vs. in-memory, scope regexes, ReindexScan, and CLIO_INDEXER_PASSIVE.

Plus addressing (CLIO_CTE_POOL), compose ordering rules, and a trim-the-chain table.

Environment variables

Added a full reference section to deployment/configuration.md: startup, client/transport, SHM ingest tuning (CLIO_SHM_IN_SHARDS / _ASYNC_SEND / _CLIENT_SPIN_US), CTE, CFS adapters, bdev stats, task scheduling, logging, and the ADIOS2 large-scale init-stagger vars.

Corrected CLIO_IPC_MODE in configuration.md and quick-start.mdx — it was documented as "TCP default", but unset actually auto-probes SHM → IPC → TCP.

Default compose file

The docs showed a three-module compose. Replaced with the actually-shipped clio_default.yaml: CAE at its own pool 400.0 forwarding to CTE, a persistent disk tier with persistence_level, performance.metadata_log_path, and the full chain.

Also documented config keys that had no coverage: learning_rate, main_segment_size, metadata_segment_size, conf_dir, the gpu and swim sections, existing_pool_id / existing_pool_module, gpu_metadata_cache, and CAE transparent LLM labeling.

Refreshed both Docker Compose examples, including a volume for ~/.clio/ — the default config now writes the persistent tier, metadata log, and search index there, so without one they vanish on docker compose down.

FUSE adapter: Linux, macOS, and Windows

The FUSE adapter page documented Linux only, but the adapter runs on all three platforms — the callbacks and the CTE data path below them are identical everywhere; only the kernel backend and the mount mechanics differ.

Added a platform support matrix and split Installation, Mount, and Unmount into per-platform tabs:

	Linux	macOS	Windows
Backend	libfuse3	macFUSE 5 (ships libfuse3)	WinFsp 2.0
Ships in the wheel	Yes	No — source build	Yes
Mountpoint	Any directory	Directory (kext) or under /Volumes (FSKit)	Drive letter or directory
Unmount	fusermount3 -u	umount / diskutil unmount force	Stop the daemon
Discovery	pkg-config fuse3	pkg-config fuse3	WINFSP_ROOT (no .pc file)

The details that actually bite:

• macOS is a source build — the wheel does not ship clio_cte_fuse. The release-mac-fuse preset builds it against macFUSE 5. Mounting needs either the kext (one-time Recovery-Mode approval + reboot) or the kext-free FSKit backend (-o backend=fskit, macFUSE 5.1+ on macOS 15.4+, mountpoint must be under /Volumes). CI enforces the macOS build and unit/ops suites but the mount smoke is a non-blocking probe, so this is the least-proven path and the page says so.
• Windows needs ADDLOCAL=ALL on the WinFsp MSI — the Developer feature is what provides inc/fuse3 + the import library. WinFsp ships no pkg-config file, so it's located by path (WINFSP_ROOT, default %ProgramFiles(x86)%\WinFsp).
• A missing backend skips the adapter rather than failing the build, so the symptom is a silently absent binary. The troubleshooting section leads with that.

Also documented the Apptainer --fusemount path (CLIO_CTE_FUSE_MOUNTPOINT is mandatory since Apptainer communicates the mountpoint through neither argv nor the environment; needs CAP_SYS_ADMIN in the userns) — including that it is compiled out of the published Linux wheel, because manylinux ships libfuse 3.10.2 and the custom-io path needs 3.14+ headers at build time. Plus the CI mount-smoke scripts as an end-to-end deployment check, and a platform-keyed troubleshooting section.

The supported-operations table was stale. rename, chmod, chown, symlink, readlink, link, statfs, and all four xattr ops are implemented, and truncate is a real AsyncTruncate rather than the documented "updates cached size". Replaced the "not yet supported" list with what genuinely isn't (RENAME_EXCHANGE/RENAME_WHITEOUT, fallocate punch/collapse/insert) and documented the caching semantics — kernel attr/entry caches are off because there is no invalidation upcall, page cache is on because mmap depends on it.

Finally, noted in the adapter comparison that POSIX/STDIO/VFD are Linux-only (glibc ELF/dlsym interceptor, no macOS or Windows port), so FUSE is the only transparent-interception option on the other two.

Two things worth a closer look

1. deprecation-notes.md was wrong in a dangerous direction. It claimed the CHI_* env vars, <chimaera/…> / <hermes_shm/…> headers, the hshm:: / hipc:: / HSHM_* / CHI_* macros, the ~/.chimaera/ config paths, and the chimaera CLI symlink all still worked as aliases. None of them do — GetCompat() now reads only CLIO_<suffix>, the shim trees are gone, and all four config-lookup candidates are ~/.clio/clio.yaml.

The failure mode is quiet: an unset env var is not an error, so a launch script still exporting CHI_SERVER_CONF or CHI_PORT starts the runtime successfully on the wrong configuration. Rewrote the page around what was removed, made the migration sweep mandatory rather than optional, and kept the two aliases that genuinely survive (clio_cae_omni, and the nested clio_run runtime … / clio_run repo refresh forms).

2. CMake naming was stale across six pages. The real targets are clio::run::admin_client / clio_cte::core_client, the umbrella package is find_package(clio-core CONFIG REQUIRED), the helper is ClioCoreCommon.cmake, and the runtime define is CLIO_RUNTIME=1 (not CHIMAERA_RUNTIME=1). Fixed in the module dev guide, the three base-module pages, cte.md, the scheduler guide, monitoring, hpc-cluster, and the module test guide.

Also

• Fixed three pre-existing broken TOC anchors in the module dev guide.
• Added sidebar_position / frontmatter to the CTE pages so the section orders sensibly.

Verification

npx docusaurus build completes with no broken links and no broken anchors. Every claim above was checked against the source in clio-core (task/config headers, clio_default.yaml, config_manager.cc, ipc_manager.cc, ClioCoreCommon.cmake, the Dockerfiles) rather than inferred.

🤖 Generated with Claude Code