wrapper design
- source boundary
- this tree contains the public wrapper source
- it does not contain private Midas Lex source or guidance data
- the real Midas Lex binary is a release asset
- command path
- `midas-lex` is the only user command
- startup parses an optional leading selector, resolves the runtime, and passes every remaining argument unchanged
- with no selector, an installed verified runtime starts first; the wrapper then starts a separate background child for the throttled update check and waits for the runtime child
- the background child is marked with private environment variables and a one-use marker, performs one release lookup for wrapper and runtime checks, logs failures without changing the running command, and exits without starting the runtime
- a first run with no installed runtime installs the selected latest release before starting it, so no background update child is needed for that invocation
- `midas-lex +v0.0.1-alpha.1 ...` selects an exact installed or downloadable release
- `midas-lex +prerelease ...` selects the newest non-draft semver release, including pre-release tags
- explicit `+prerelease` selection is the only latest pre-release opt-in path
- all other arguments, including unrecognized leading `+` tokens, are passed to the real binary unchanged
- environment variables are inherited by the real binary
- install path
- `MIDAS_LEX_VERUS_HOME` overrides storage
- `XDG_DATA_HOME` changes default storage to `$XDG_DATA_HOME/midas-lex/verus`
- fallback storage is `$HOME/.midas-lex/verus`
- real binaries live under `toolchains/VERSION/TARGET/`
- checksum records live under `checksums/VERSION/`
- install lock lives at `locks/install.lock`
- lock scope is one `MIDAS_LEX_VERUS_HOME` data directory
- diagnostics
- default operational logs are hidden
- `MIDAS_LEX_VERUS_VERBOSE=1` logs the selected runtime tag and binary path
- `MIDAS_LEX_VERUS_LOG=info` logs download and update checks
- release lookup
- the wrapper reads GitHub releases from `MidasAl/midas-lex`
- downloaded runtime assets are named
`midas-lex-private-VERSION-TARGET[.exe]`
- latest release selection prefers stable releases
- latest release selection falls back to pre-releases when no stable release exists
- latest release selection excludes drafts
- release tags are ordered as semantic versions
- default runs use the latest installed local ordinary release
- first runs download the latest stable release, or latest pre-release when no stable release exists
- background checks use the same stable-preferred release selection for the next invocation
- update timer
- update checks are throttled by a stamp file in a private per-user system-temp directory
- the interval is 1 hour per platform
- a file lock serializes timer claims across concurrent wrapper processes
- integrity
- each binary asset has a same-name `.sha256` asset
- checksum mismatch stops installation
- partially downloaded files are never executed
- automatic wrapper update
- a default run with an installed verified runtime starts that runtime before the background update child
- first runs and explicit selectors do not start the automatic update child
- wrapper selection reuses the background child's stable-preferred, non-draft semantic-version release from `MidasAl/midas-lex`
- the selected asset is `midas-lex-VERSION-TARGET[.exe]`; runtime asset selection remains unchanged
- Linux and macOS resolve the running executable, stage beside it, verify the exact one-line checksum record, preserve its mode, sync, and atomically rename
- an adjacent file lock serializes updates; the running executable digest is checked before and after waiting and again before rename
- ordinary errors delete the staged file and preserve the installed wrapper
- release validity and semantic version comparison precede path resolution and platform handling; equal or older releases cause no download or notice
- only a newer Windows release produces a normal warning naming the canonical running `.exe` path and directing users to `cargo install midas-lex --force`
- the Windows warning and skipped replacement do not fail the current runtime or stop its independent update check
- safe local walkthrough
- `cargo test` exercises selector and pass-through parsing, first-run policy, release ordering, data-directory selection, timer, marker, locks, independent update failures, checksum cleanup, atomic replacement, permissions, and platform handling
- `cargo run -- help` checks the real wrapper command path and may download a runtime when none is installed
- `MIDAS_LEX_VERUS_HOME=/tmp/midas-lex-doc-check cargo run -- +v0.0.1-alpha.1 help` checks explicit-selector parsing but may download the named release
- do not use the selector walkthrough against a production data directory unless the download is intended