Mercury Toolbox / 水星工具箱

Mercury Toolbox is proprietary software. See LICENSE.

Mercury Toolbox is a PowerShell-first Rust toolbox of small, focused CLI binaries for local inspection, shaping, and triage.

It is built for the kind of terminal work where you need one command to answer one concrete question quickly: what changed, what owns this port, what does this JSON look like, what symbols exist in this codebase, what imports does this PE pull in, what is inside this Unity asset, or what hash set should I emit for this release artifact.

Instead of hiding everything behind one giant control binary, Mercury keeps each capability as its own small command with a stable CLI contract, compact text output by default, and structured --json or --toon output when the next consumer is a script, another tool, or an AI model.

Quick reasons to use it:

• PowerShell-friendly by default, including stdin and pipeline behavior that stays predictable on Windows.
• AI-readable structured output through native --json and --toon modes.
• Narrow commands that are easier to remember, script, package, test, and reason about than one monolithic Swiss-army binary.
• Coverage across code reading, logs, Git/repo shape, config editing, ports/processes, .NET/Unity inspection, PE/LLVM triage, CSV/JSON/SQL shaping, and release hashing through mhash.

Fast starter commands:

fileprobe <PATH>
reposhape . --json | ConvertFrom-Json
diagpick .\build.log
mhash --algorithm sha256,blake3-256 .\dist\MercuryToolbox.zip --json | ConvertFrom-Json
peimports .\target\release-fast\portping.exe --json | ConvertFrom-Json

Recommended first read:

• Install if you want the toolbox on your machine now.
• Which Tool First if you want the shortest route to the right command.
• Commands if you want the full tool map.
• docs/jade-discipline.md if you are contributing code or changing shared contracts.
• docs/maintainer-notes.md before changing shared output, JSON-family formats, codeindex-family tools, or Jade gates.

Architecture

• crates/common carries the shared CLI contract, exit codes, JSON/text/TOON rendering rules, compact JSON-family format helpers, and stdin policy.
• Set $env:MERCURY_OUTPUT='json' or $env:MERCURY_OUTPUT='toon' when you want the whole toolbox to default to one structured format for an AI-heavy shell session.
• JSON-capable tools should use native --toon or --format toon; reserve the standalone toon binary for external JSON producers or explicit format conversion.
• codeshape and defsnip both ride on the shared codeindex AST engine, so their JSON now exposes engine=codeindex.
• Managed inspection stays split on purpose: asmtype finds candidate types, asmmember drills into members, asmflow handles IL and xrefs, and JSONL piping lets them hand off without copy-paste.
• Unity-focused inspection builds on shared layers instead of one-off scripts: unityasset covers offline assets, unitydiag covers logs, and unityprobe covers read-only runtime inspection through an explicit BepInEx bridge install.

Modern CLI Pairing

• Mercury is meant to work with modern terminal companions, not replace them: rg, fd, bat, jq, yq, sd, xh, tokei, eza, procs, dust, hyperfine, hexyl, zoxide, lazygit, delta, tealdeer, and ouch.
• Prefer rg over recursive grep or Select-String, fd over Get-ChildItem -Recurse, bat or Mercury readers over raw Get-Content, jq or yq over manual JSON or YAML parsing, and xh over curl for quick HTTP checks.
• Prefer Mercury when the question is “what is the shape of this local thing?” and prefer the companion tool when the question is “which local thing should I open next?”
• just is the fast command hub for this repo, and bacon is the watch loop that keeps either workspace-wide or subsystem-scoped checks running while you keep editing.

Which Tool First

Start from the job, not from the command name. The table below is the quick routing layer for a fresh shell or an AI agent that has not seen the artifact yet.

Job	First command	Follow-up lane
I have an unknown file	fileprobe <PATH>	binmeta, stringscan, snip, or chunkcat depending on the detected shape
I have a repo and need the map	reposhape . --json	codeshape, gitshape, dotnetshape, sqlshape, or ctxpack
I have source and need one symbol	defsnip <SYMBOL> .	refs <SYMBOL> ., then hitsnip or ctxpack for handoff
I have a log or build failure	diagpick <LOG>	logshape, snip --match, or runprobe for the repro command
I have a .NET or Unity DLL	asmref diagnose <ASSEMBLY> --resolve-dir <DIR>	asmtype, asmmember, asmflow, and asmapi diff
I have a Windows EXE or DLL	peimports <PATH>	peexports, pecalls, pesig, pestrrefs, llvmreadobj, or llvmobjdump
I have a Windows driver	drvshape <SYS>	ioctlscan, peimports --category device_io, pecalls --category device_io, and pestrrefs
I need an AI-readable handoff	Add --json for tooling or --toon for model input	Pipe external JSON through toon only when the producer is not already a Mercury command

Safe starter commands are intentionally read-only:

fileprobe <PATH>
reposhape . --json | ConvertFrom-Json
asmref diagnose <ASSEMBLY> --resolve-dir <DIR> --format toon
peimports <PATH> --json | ConvertFrom-Json
drvshape <SYS> --json | ConvertFrom-Json

Every command has guided triage notes in the generated AI prompt and Codex skill catalog: an answer shape, a trust basis, and likely next actions. PE deep-analysis commands additionally emit that guidance at runtime through an answer-first text header plus report_quality and next_actions in structured output. Use those fields as the first trust check before inventing an ad-hoc pipeline.

Install

Recommended on Windows + PowerShell:

pwsh -NoProfile -File .\scripts\install-toolbox.ps1

Default install behavior:

• builds all toolbox binaries in ReleaseFast
• stages versioned binaries under $env:LOCALAPPDATA\MercuryToolbox\versions\...
• updates the stable command directory at $env:LOCALAPPDATA\MercuryToolbox\current\bin
• refreshes the generated AI prompt and Codex skill assets
• copies docs and AI assets into $env:LOCALAPPDATA\MercuryToolbox\share\mercury-toolbox
• installs the generated mercury-toolbox Codex skill into $env:CODEX_HOME\skills when CODEX_HOME is set, otherwise into $HOME\.codex\skills
• adds that stable command directory to the user PATH when missing
• updates the installer process PATH and prints a reload snippet for shells launched via pwsh -File
• installs every toolbox command: cjson, ison, isonl, zon, tonl, jsonlgrep, jsonshape, mhash, recent, pathshadow, portping, portunlock, msudo, asmtype, asmmember, asmref, asmapi, asmflow, llvmobjdump, llvmreadobj, llvmnm, peexports, peimports, pecalls, pesig, pestrrefs, drvshape, ioctlscan, binmeta, fileprobe, outline, codeshape, refs, snip, defsnip, ctxpack, chunkcat, hitsnip, diagpick, logshape, stringscan, toon, csvshape, sqliteshape, sqlshape, unityasset, unityprobe, unitydiag, envdiff, proctree, sysshape, runprobe, await, argv, config, gitshape, reposhape, dotnetshape, unlock

If you launch the installer as a child PowerShell process, reload the current shell afterward:

$env:Path = [Environment]::GetEnvironmentVariable('Path','User') + ';' + [Environment]::GetEnvironmentVariable('Path','Machine')

Useful install variants:

pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -Configuration Debug
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -Configuration ReleaseSize
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -SkipSlimBinaryRebuild
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -InstallRoot C:\Tools\MercuryToolbox
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -CodexHome C:\Tools\CodexHome
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -NoCodexSkillInstall
pwsh -NoProfile -File .\scripts\install-toolbox.ps1 -NoPathUpdate

Remove the toolbox again with:

pwsh -NoProfile -File .\scripts\uninstall-toolbox.ps1

If you installed into a custom root, pass the same root to uninstall:

pwsh -NoProfile -File .\scripts\uninstall-toolbox.ps1 -InstallRoot C:\Tools\MercuryToolbox

Manual Rust-native fallback:

cargo install --path .\crates\snip

Portable Package

Build a portable release bundle with binaries, package install scripts, manifest, checksums, the combined AI prompt, and the generated Codex skill:

pwsh -NoProfile -File .\scripts\package-toolbox.ps1

The first hosted package is documented in the v0.1.0 release notes, and hosted archives live on the Gitea releases page. For an offline install, download MercuryToolbox-x86_64-pc-windows-msvc-ReleaseFast.zip, extract it, then run the package installer shown below.

Default package behavior:

• builds the full workspace in ReleaseFast
• refreshes docs\ai\mercury-toolbox-ai-prompt.md
• refreshes skills\mercury-toolbox\
• stages a portable directory under .\dist\MercuryToolbox-<host-target>-ReleaseFast
• writes SHA256SUMS.txt and mercury-toolbox-package.json
• creates a matching .zip archive you can copy to another machine

Useful package variants:

pwsh -NoProfile -File .\scripts\package-toolbox.ps1 -Configuration ReleaseSize
pwsh -NoProfile -File .\scripts\package-toolbox.ps1 -SkipSlimBinaryRebuild
pwsh -NoProfile -File .\scripts\package-toolbox.ps1 -OutputRoot C:\Artifacts
pwsh -NoProfile -File .\scripts\package-toolbox.ps1 -PackageName MercuryToolbox-custom

Install directly from an extracted package without the Rust toolchain:

pwsh -NoProfile -File .\dist\MercuryToolbox-<host-target>-ReleaseFast\scripts\install-package-toolbox.ps1

That package installer:

• stages packaged binaries under $env:LOCALAPPDATA\MercuryToolbox\versions\...
• updates the stable command directory at $env:LOCALAPPDATA\MercuryToolbox\current\bin
• copies the AI prompt, generated skill, manifest, and checksums into $env:LOCALAPPDATA\MercuryToolbox\share\mercury-toolbox
• installs the generated mercury-toolbox Codex skill into $env:CODEX_HOME\skills when CODEX_HOME is set, otherwise into $HOME\.codex\skills
• updates the user PATH, and prints the same reload snippet for shells launched via pwsh -File, unless -NoPathUpdate is used

Remove a package install again with:

pwsh -NoProfile -File .\dist\MercuryToolbox-<host-target>-ReleaseFast\scripts\uninstall-package-toolbox.ps1

Build Profiles And Size Tuning

ReleaseFast is the default installer and packager configuration. It uses opt-level=3, fat LTO, one codegen unit, panic=abort, stripped symbols, and no debug info for fast runtime in portable binaries. This is intentionally slower to compile than debug or plain release builds.

ReleaseSize uses the same fat LTO, single-codegen-unit, stripped, aborting baseline with opt-level="z" for the smallest binaries and packages. Use it when archive size matters more than throughput, then run the probe gate to compare actual sizes:

pwsh -NoProfile -File .\scripts\probe-toolbox.ps1 -BuildProfile ReleaseSize -SkipBenchmarks

The install and package scripts perform a second "slim rebuild" pass for selected codeindex-heavy tools after the workspace build. Keep the default for release artifacts. Use -SkipSlimBinaryRebuild only for faster local iteration when you can accept potentially larger selected binaries.

Portable packages deliberately do not set target-cpu=native. For a local-only build on the current machine, opt in from the shell:

$env:RUSTFLAGS = '-Ctarget-cpu=native'
cargo build --profile release-fast -p mercury-mhash --bin mhash
Remove-Item Env:\RUSTFLAGS

Commands

HIGH RISK: msudo is the top-level high-risk toolbox command because it can cross the Windows privilege boundary. Start with safe discovery first: msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated, then inspect msudo --help or msudo run --help before any explicit run request.

Tool Map

Every command supports --help, compact text by default, and structured output through --json, --toon, or --format text|json|toon unless a command-specific format flag is explicitly documented.

Area	Tool	Primary use	Fast start
Data and config	cjson	Compact JSON or JSONL.	cjson <PATH>
Data and config	ison	Convert JSON and ISON.	ison <PATH>
Data and config	isonl	Convert JSONL and ISONL.	isonl --from jsonl --to isonl <PATH>
Data and config	zon	Convert JSON/JSONL and ZON.	zon <PATH>
Data and config	tonl	Query, validate, index, stream, and ETL TONL.	tonl query --where active=true <PATH>
Data and config	mhash	Hash, manifest, verify, and benchmark files.	mhash --algorithm sha256 <PATH>
Data and config	jsonlgrep	Filter and project JSONL or JSON arrays.	jsonlgrep level=error <PATH>
Data and config	jsonshape	Summarize or diff JSON shape.	jsonshape <PATH>
Data and config	csvshape	Summarize or diff CSV/TSV shape.	csvshape <PATH>
Data and config	sqliteshape	Inspect or diff SQLite schema/table shape.	sqliteshape <PATH>
Data and config	sqlshape	Inspect or diff normalized SQL schema across engines.	sqlshape --engine sqlite --url <PATH>
Data and config	config	Read or edit JSON/YAML/TOML/env/INI config.	config get <PATH> /version
Data and config	toon	Convert external/raw JSON and TOON.	'{"ok":true}' | toon
Code and context	recent	List fresh files or directories.	recent --root . --since 2h
Code and context	pathshadow	Explain PATH winners and shadowed commands.	pathshadow rg --summary
Code and context	fileprobe	Classify files before opening them.	fileprobe <PATH>
Code and context	outline	List top-level source or config structure.	outline <PATH>
Code and context	codeshape	Map repo files and AST declarations.	codeshape .
Code and context	refs	Find symbol references or callers.	refs helper .
Code and context	snip	Extract exact lines, matches, or symbols.	snip --lines 16:27 <PATH>
Code and context	defsnip	Extract full AST-backed definitions.	defsnip helper .
Code and context	ctxpack	Pack files/snippets/hits/diagnostics for prompts.	ctxpack <PATH>
Code and context	chunkcat	Read large files in bounded chunks.	chunkcat <PATH> --max-lines 40
Code and context	hitsnip	Turn search hits into merged snippets.	rg -nH "helper" . | hitsnip --def
Code and context	diagpick	Extract actionable diagnostics from logs.	diagpick <PATH> --def
Code and context	gitshape	Summarize Git status and diffs.	gitshape status
Code and context	reposhape	Detect repo ecosystems and entrypoints.	reposhape .
Code and context	dotnetshape	Inspect .NET project graphs and MSBuild config shape.	dotnetshape .
Logs and runtime	logshape	Group repetitive log lines.	logshape <PATH>
Logs and runtime	stringscan	Extract and classify strings from blobs.	stringscan <PATH>
Logs and runtime	envdiff	Snapshot, diff, or wrap environment changes.	envdiff run --shell pwsh -- <COMMAND>
Logs and runtime	proctree	Inspect system, rooted, or command process trees.	proctree system
Logs and runtime	sysshape	Capture machine, shell, env, and tool shape.	sysshape --group shell
Logs and runtime	runprobe	Run one command and capture a stable result object.	runprobe --shell raw -- <COMMAND>
Logs and runtime	await	Poll paths, ports, HTTP, or commands.	await path <PATH> --state exists
Logs and runtime	argv	Quote argv or inspect shell argument passing.	argv quote --shell pwsh -- git status
Network and locks	portping	Probe TCP/HTTP/HTTPS with timings.	portping tcp://127.0.0.1:80
Network and locks	portunlock	Show or free local port owners.	portunlock who 3000
Network and locks	unlock	Inspect file lockers and unlock-aware file actions.	unlock who <PATH>
Network and locks	msudo	Inspect elevation state before privileged launches.	msudo status --json
Managed, Unity, binary	asmtype	Find managed assembly types.	asmtype <ASSEMBLY> --match SpaceCraft
Managed, Unity, binary	asmmember	Inspect managed type members.	asmmember --assembly <ASSEMBLY> <TYPE>
Managed, Unity, binary	asmref	Inspect managed assembly references and dependency closure risks.	asmref diagnose <ASSEMBLY> --resolve-dir <DIR>
Managed, Unity, binary	asmapi	Diff managed public API surfaces.	asmapi diff <OLD_DLL> <NEW_DLL>
Managed, Unity, binary	asmflow	Inspect managed IL bodies and xrefs.	asmflow find <ASSEMBLY> --match Start
Managed, Unity, binary	llvmobjdump	Summarize LLVM objdump sections and disassembly.	llvmobjdump <PATH> --json
Managed, Unity, binary	llvmreadobj	Inspect COFF/PE headers, sections, imports, exports, and debug hints through LLVM.	llvmreadobj <PATH> --json
Managed, Unity, binary	llvmnm	List and classify object symbols through LLVM nm output.	llvmnm <PATH> --defined-only --json
Managed, Unity, binary	peexports	Deeply inspect PE export tables.	peexports <DLL> --json
Managed, Unity, binary	peimports	Categorize PE import tables by API family.	peimports <DLL> --category device_io --json
Managed, Unity, binary	pecalls	Extract imported API callsites from LLVM disassembly.	pecalls <DLL> --api WSAStartup --json
Managed, Unity, binary	pesig	Infer PE function boundaries and calling convention hints.	pesig <DLL> --min-confidence medium --json
Managed, Unity, binary	pestrrefs	Find strings and direct cross-references in PE code.	pestrrefs <DLL> --contains DeviceIoControl --json
Managed, Unity, binary	drvshape	Summarize likely Windows driver traits and hints.	drvshape <SYS> --json
Managed, Unity, binary	ioctlscan	Scan PE bytes for probable Windows IOCTL constants.	ioctlscan <SYS> --json
Managed, Unity, binary	binmeta	Inspect file metadata, PE basics, version resources, and Windows signature identity.	binmeta <PATH>
Managed, Unity, binary	unityasset	Inspect offline Unity assets and bundles.	unityasset index <GAME_DATA>
Managed, Unity, binary	unityprobe	Query an explicit read-only BepInEx bridge.	unityprobe status --game-root <GAME>
Managed, Unity, binary	unitydiag	Summarize Unity and BepInEx logs.	unitydiag --game-root <GAME> --latest

cjson

Compact JSON or JSONL into single-line output, with an optional stable recursive key sort for diffing, caching, and AI-friendly ingestion.

cjson .\fixtures\cjson\sample.json
bat --style=plain --paging=never .\fixtures\cjson\records.jsonl | cjson --input-format jsonl --sort-keys
cjson --sort-keys --json .\fixtures\cjson\sample.json | ConvertFrom-Json

ison / isonl / zon / tonl

Work with the compressed JSON family without adding Node or TypeScript runtime dependencies. ison, isonl, and zon are format converters; tonl also includes query, validate, index, streaming query, and ETL commands. Use --toon or --format toon when the wrapper output itself is going to an AI/model.

ison .\fixtures\json-family\ison\users.json
isonl --from isonl --to jsonl .\fixtures\json-family\ison\users.isonl
zon .\fixtures\json-family\zon\person.json --toon
tonl query --where active=true .\fixtures\json-family\tonl\records.tonl --format toon

jsonlgrep

Filter JSONL, single-line JSON arrays, or line-oriented logs with field selectors, negation, nested paths, projections, and JSON output.

jsonlgrep level=error .\fixtures\jsonl\events.jsonl --pick ts,msg
jsonlgrep event.user.name!=alice .\nested.jsonl --pick event.user.name,status
bat --style=plain --paging=never .\fixtures\jsonl\events.jsonl | jsonlgrep 'msg~=login' --count --json | ConvertFrom-Json
recent --root . --limit 20 --json | jsonlgrep 'path~=LogOutput' --pick modified_rfc3339,path --json | ConvertFrom-Json

jsonshape

Summarize JSON or JSONL structure into compact path statistics, or diff two shape reports when you want additions, removals, and changed kinds without opening the raw payloads.

jsonshape .\fixtures\reading\config.json
jsonshape .\fixtures\jsonshape\events.jsonl --input-format jsonl --json | ConvertFrom-Json
jsonshape .\fixtures\toon\config.json --limit 8
jsonshape diff .\fixtures\reading\config.json .\fixtures\toon\config.json --json | ConvertFrom-Json

mhash

Compute high-performance OpenHashTab-class file mhashs, write JSONL manifests, verify manifests, list the supported algorithm matrix, and benchmark hash throughput without leaving PowerShell-friendly CLI flows.

mhash defaults to SHA-256 text output for simple local checks. Use --algorithm for explicit multi-algorithm hashing, --all when you want the full OpenHashTab-class matrix, --json or --format jsonl for machine handoff, and --manifest when the hash run should produce a reusable verification file. mhash verify reads Mercury JSONL manifests and common checksum-style lines; pass exactly one --algorithm when verifying checksum-style text that does not name the algorithm.

mhash .\README.md
mhash --algorithm sha256,blake3-256,xxh3-128 .\dist\MercuryToolbox.zip
mhash list-algorithms
mhash list-algorithms --json | ConvertFrom-Json | Sort-Object family,name
fd -t f . .\dist | mhash --input-format lines --algorithm sha256,blake3-256 --format jsonl | jq -r '.algorithm + " " + .path'
mhash --recursive --ignore target --all --manifest .\checksums.jsonl .\dist --jsonl
mhash verify .\checksums.jsonl --json | ConvertFrom-Json
mhash bench --algorithm sha256,blake3-256,xxh3-128 .\dist\MercuryToolbox.zip
hyperfine 'mhash --algorithm sha256 .\dist\MercuryToolbox.zip' 'mhash --algorithm blake3-256 .\dist\MercuryToolbox.zip'

recent

List recently modified files or directories, respecting .gitignore by default and filtering by extension, kind, or basename regex.

recent --root . --since 2h --ext rs --name '^(lib|main)$'
'.' | recent --kind dir --limit 10
'.' | recent --limit 5 --json | ConvertFrom-Json

pathshadow

Inspect command resolution order across PATH, explain who wins, and find every duplicate command available to the shell. Use --shell powershell when AI work needs the actual PowerShell winner, including aliases and cmdlets, and --high-signal --summary when full duplicate scans are too noisy.

pathshadow rg
pathshadow python npm --shell powershell
'cargo' | pathshadow --json | ConvertFrom-Json
pathshadow --all-duplicates --high-signal --summary --json | ConvertFrom-Json

portping

Probe TCP, HTTP, and HTTPS targets and emit compact timing summaries or JSON records with method and status expectation support.

portping tcp://127.0.0.1:80
portping https://example.com/health --method HEAD --expect-status 200
'https://example.com' | portping --json | ConvertFrom-Json

portunlock

Inspect local TCP or UDP port owners on Windows and, when needed, free the port by terminating only the exact remaining owning processes.

portunlock who 3000
portunlock free --force 5000
'5000' | portunlock who --json | ConvertFrom-Json

msudo

Inspect the current Windows elevation relay status and, when you explicitly choose to cross that boundary, launch a one-shot elevated child process through the configured host.

Reliable today: one-shot current-process, current-user, admin, system, and trustedinstaller commands, foreground --same-console launches in the current terminal, active-session targeting for duplicated high-privilege tokens, and interactive SYSTEM / TrustedInstaller shells either in a new window or in the current console when --same-console is explicit. The CLI is intentionally native to Mercury rather than syntax-compatible with gsudo or NSudo; use explicit options such as --user trustedinstaller --dangerous --privileges enable-all. For high-risk flows, start with msudo status --json and keep the requested command explicit.

HIGH RISK: The global msudo rule above applies here too: inspect with msudo status --json, check --help before using new flags, and relay only the exact command you intend to run.

For --user trustedinstaller, verify the token with whoami /groups, not just whoami /user: the launch runs from the TrustedInstaller service token, so the user SID still reports NT AUTHORITY\SYSTEM while the token carries the NT SERVICE\TrustedInstaller service SID.

msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated
msudo --help
msudo run --help
msudo --user trustedinstaller --dangerous --privileges enable-all --integrity system --wait -- cmd /d /c whoami /groups
msudo --same-console --user system --dangerous --shell powershell

asmtype

List managed assembly types with compact filters for Unity and general .NET reverse-engineering flows. --with-member-match lets you keep only the types whose members look relevant, --show-matched-members explains why each type survived that pass while preferring user-facing hits over auto-property backing fields when both are present, --pick trims the output for pipelines, --base is the fast “derived from this base type” filter, and --intent unity-spacecraft-workflow bakes in a good first-pass keyword bundle.

asmtype .\fixtures\managed\bin\GameAssembly.dll --match SpaceCraft
asmtype .\fixtures\managed\bin\GameAssembly.dll --with-member-match 'StartProject|QueueVehicle'
asmtype .\fixtures\managed\bin\GameAssembly.dll --with-member-match 'Build|Launch' --show-matched-members --json | ConvertFrom-Json
asmtype .\fixtures\managed\bin\GameAssembly.dll --base '^Game\.ObjectInfoDataScripts\.ProductionItem$' --pick full_name,base_type
asmtype .\fixtures\managed\bin\GameAssembly.dll --with-member-match 'k__BackingField' --user-code-only
'C:\game\Managed\Assembly-CSharp.dll' | asmtype --input-format lines --intent unity-spacecraft-workflow --json | ConvertFrom-Json
'C:\game\Managed\Assembly-CSharp.dll' | asmtype --input-format lines --match 'Rocket|Launch'
asmtype .\fixtures\managed\bin\GameAssembly.dll --namespace 'Game\.UI' --json | ConvertFrom-Json

asmmember

List methods, fields, and properties from managed types without hand-written reflection scripts. It now accepts JSONL rows from asmtype --json, so AI flows can go from “find likely types” to “inspect their members” without copying names around. --pick trims multi-type pipelines down to the fields you actually want, --user-code-only hides compiler-generated backing fields and closure artifacts, and the Unity intent preset turns that on automatically.

asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll Game.UI.Windows.Windows.SpaceCraftConstructionWindow
asmtype .\fixtures\managed\bin\GameAssembly.dll --intent unity-spacecraft-workflow --json | asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll --input-format jsonl --intent unity-spacecraft-workflow --json | ConvertFrom-Json
'Game.UI.Windows.Windows.SpaceCraftConstructionWindow' | asmmember --assembly C:\game\Managed\Assembly-CSharp.dll --input-format lines --match 'Build|Launch'
asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll Data.SpacecraftConstructData --pick kind,name,visibility,signature
asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll Data.SpacecraftConstructData --user-code-only
asmmember --assembly .\fixtures\managed\bin\GameAssembly.dll Data.SpacecraftConstructData --binding public,nonpublic,instance,static --json | ConvertFrom-Json

asmref

Inspect managed assembly references and see which dependencies resolve from nearby directories. Use diagnose for Unity/.NET/Rocket plugin dependency closure checks, including missing references, same-name candidate conflicts, winning DLLs, test-only leaks, and obvious MissingMethod/TypeLoad risks.

asmref .\fixtures\managed\bin\GameAssembly.dll --resolve-dir .\fixtures\managed\bin
asmref diagnose .\fixtures\managed\bin\GameAssembly.dll --resolve-dir .\fixtures\managed\bin --format toon
asmref diagnose .\RootPlugin.dll --test-only-pattern Project.Tests --no-default-test-patterns --json | ConvertFrom-Json
'C:\game\Managed\Assembly-CSharp.dll' | asmref --input-format lines --resolve-dir C:\game\Managed --json | ConvertFrom-Json
asmref .\fixtures\managed\bin\GameAssembly.dll --json | ConvertFrom-Json

asmapi

Diff two managed assemblies by normalized type and method API. Public API is the default; use --visibility internal or --visibility all when reverse-engineering non-public compatibility, and use --include-special when property/event accessor methods should be visible.

asmapi diff old\0Harmony.dll new\0Harmony.dll
asmapi diff Rocket.API.old.dll Rocket.API.new.dll --json | ConvertFrom-Json
asmapi diff old.dll new.dll --visibility all

asmflow

Inspect managed method bodies, decoded IL, callers, callees, field access, and string literals when type/member lists are not enough. Use find to locate candidate methods, body to inspect the IL window, and xref to understand call flow.

asmflow find .\fixtures\managed\bin\GameAssembly.dll --match 'StartProject|QueueVehicle'
asmflow body --assembly .\fixtures\managed\bin\GameAssembly.dll 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartProject'
asmflow xref --assembly .\fixtures\managed\bin\GameAssembly.dll 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartLaunch' --direction both
asmflow xref --assembly .\fixtures\managed\bin\GameAssembly.dll 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartLaunch' --direction callers --virtual --json | ConvertFrom-Json

llvmobjdump

Run llvm-objdump through Mercury's LLVM backend discovery and turn section tables, symbol labels, and disassembly rows into compact text, JSON, or TOON.

llvmobjdump .\target\release-fast\binmeta.exe --json | ConvertFrom-Json
llvmobjdump .\target\release-fast\binmeta.exe --section .text --toon

llvmreadobj

Run llvm-readobj through Mercury's LLVM backend discovery and summarize COFF/PE file headers, sections, imports, exports, debug directories, and CodeView/PDB hints.

llvmreadobj .\target\release-fast\binmeta.exe --json | ConvertFrom-Json
llvmreadobj .\target\release-fast\binmeta.exe --debug-directory --toon

llvmnm

Run llvm-nm through Mercury's LLVM backend discovery and parse POSIX-style symbol rows, including object prefixes and source-line hints when LLVM emits them.

llvmnm .\target\release-fast\binmeta.exe --defined-only --json | ConvertFrom-Json
llvmnm .\target\release-fast\binmeta.exe --undefined-only --toon

peexports

Inspect PE export tables with ordinals, RVAs, forwarders, and entrypoint hints.

peexports C:\Windows\System32\kernel32.dll --json | ConvertFrom-Json
peexports C:\Windows\System32\kernel32.dll --forwarders-only --toon

peimports

Inspect and categorize PE imports by API family so you can spot filesystem, registry, device I/O, NT, and network usage quickly.

peimports .\target\release-fast\portping.exe --category device_io --json | ConvertFrom-Json
peimports .\target\release-fast\portping.exe --library kernel32.dll --toon

pecalls

Extract imported API callsites from LLVM disassembly and keep unresolved rows separate from confirmed import hits.

pecalls .\target\release-fast\portping.exe --api WSAStartup --json | ConvertFrom-Json
pecalls .\target\release-fast\binmeta.exe --category device_io --include-jumps --toon

pesig

Infer function boundaries and calling-convention hints from PE code shape and symbol labels.

pesig .\target\release-fast\portping.exe --min-confidence medium --json | ConvertFrom-Json
pesig .\fixtures\managed\bin\GameAssembly.dll --min-confidence medium --toon

pestrrefs

Scan ASCII and UTF-16LE strings, then surface direct cross-references when LLVM disassembly can prove them.

pestrrefs .\target\release-fast\portping.exe --contains DeviceIoControl --json | ConvertFrom-Json
pestrrefs .\fixtures\managed\bin\GameAssembly.dll --encoding both --min-len 6 --toon

drvshape

Summarize likely driver shape, including WDM, KMDF, NDIS, minifilter, and native driver hints.

drvshape C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json
drvshape C:\Windows\System32\drivers\ndis.sys --toon

ioctlscan

Scan PE bytes for probable Windows IOCTL constants and decode the CTL_CODE fields for quick triage.

ioctlscan C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json
ioctlscan C:\Windows\System32\drivers\ndis.sys --toon

binmeta

Inspect file metadata, Windows PE structure, version resources, and Authenticode/catalog signature identity with compact text output for humans and stable JSON for automation.

binmeta .\fixtures\binmeta\plain.txt
binmeta .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json
binmeta C:\Windows\System32\notepad.exe --json | ConvertFrom-Json | Select-Object path,version,signature
fd -a '^jsonlgrep\.exe$' .\target | binmeta --input-format lines --json | ConvertFrom-Json

For PE files, binmeta adds nullable version and signature objects. Version output includes common resource strings such as company, product, file version, original filename, and fixed four-part versions; signature output includes embedded certificate table presence, WinTrust status, embedded-vs-catalog signature type, catalog path/member tag when available, signer subject, chain summaries, timestamp signer, and certificate expiry fields. Signature or trust failures are reported as data and do not make binmeta fail.

fileprobe

Probe whether a file is source, config, text, or binary before opening it, and surface AI-friendly hints such as language, minified/generated status, encoding, BOM, and newline style.

fileprobe .\fixtures\reading\sample.rs
fileprobe .\fixtures\reading\minified.js --json | ConvertFrom-Json
fd -a '^sample\.rs$' .\fixtures\reading | fileprobe --input-format lines --json | ConvertFrom-Json

outline

Emit heuristic structure summaries for Rust, C#, JSON, TOML, and YAML so you can jump straight to the interesting part of a file.

outline .\fixtures\reading\sample.rs
outline --depth 1 .\fixtures\reading\config.toml
'.\fixtures\reading\config.yaml' | outline --json | ConvertFrom-Json

codeshape

Walk a code repository with tree-sitter-backed indexing and emit a compact project map of files, declarations, and signatures. The JSON report includes engine=codeindex so downstream consumers can see the shared AST source explicitly.

codeshape .\fixtures\polyglot\repo
codeshape --max-depth 1 --limit-per-file 8 .\fixtures\polyglot\repo --json | ConvertFrom-Json
'.\fixtures\polyglot\repo' | codeshape --json | ConvertFrom-Json

refs

Find exact symbol use-sites or caller summaries through the shared codeindex engine, with text fallback when AST lookup is unavailable.

refs helper .\fixtures\polyglot\repo
refs --callers helper .\fixtures\polyglot\repo --json | ConvertFrom-Json
refs --at .\fixtures\polyglot\repo\src\lib.rs:25 .\fixtures\polyglot\repo

snip

Extract precise ranges, regex neighborhoods, or heuristic symbol blocks from files or piped text with numbered output.

snip --lines 16:27 .\fixtures\reading\sample.rs
snip --symbol run .\fixtures\reading\sample.rs --json | ConvertFrom-Json
snip --around helper --context 0 .\fixtures\reading\sample.rs

defsnip

Extract full AST-backed definition blocks by exact symbol name so nearby line churn does not break your code slices. The JSON rows include engine=codeindex for the same reason as codeshape, and the text mode now warns when one symbol name resolves to multiple definitions.

defsnip helper .\fixtures\polyglot\repo
defsnip build_report . --json | ConvertFrom-Json
defsnip --kind method --parents Build .\fixtures\polyglot\repo
'.\fixtures\polyglot\repo\web\app.ts' | defsnip helper --json | ConvertFrom-Json

ctxpack

Pack files, line hits, diagnostics, snippets, and definition JSON into compact context blocks that are ready to hand to an AI agent or paste into a review note.

ctxpack .\fixtures\polyglot\repo\src\lib.rs:26
refs helper .\fixtures\polyglot\repo --json | ctxpack --input-format auto
diagpick .\fixtures\diag\rust-errors.txt --def --json | ctxpack --input-format auto --json | ConvertFrom-Json

chunkcat

Plan stable line chunks for large text files, then print only the chunk you need with optional JSON metadata for scripts and AI flows. --tail is the quick “show me the last window” mode for logs.

chunkcat .\fixtures\reading\sample.rs --max-lines 8
chunkcat .\fixtures\reading\sample.rs --max-lines 8 --chunk 2 --json | ConvertFrom-Json
chunkcat .\BepInEx\LogOutput.log --max-lines 20 --tail
fd -a '^sample\.rs$' .\fixtures\reading | chunkcat --input-format lines --chunk 0

hitsnip

Turn rg -n output or path:line[:column] hit streams into merged, numbered snippets. --def promotes those hits to the enclosing definition when codeindex supports the file, and --allow-empty keeps exploratory pipelines quiet when there were no hits.

rg -nH "Mode::" .\fixtures\reading\sample.rs | hitsnip --context 1
rg -nH "helper" .\fixtures\polyglot\repo\src\lib.rs | hitsnip --def
rg -n "error|warning" .\fixtures\diag\rust-errors.txt | hitsnip --path .\fixtures\diag\rust-errors.txt --context 1
rg -nH "DefinitelyMissing" .\fixtures\reading\sample.rs | hitsnip --allow-empty --json | ConvertFrom-Json
bat --style=plain --paging=never .\fixtures\hits\rg-output.txt | hitsnip --json | ConvertFrom-Json

diagpick

Extract actionable diagnostics from compiler and runtime logs, with optional snippets and enclosing definitions. Clean logs now say 0 actionable diagnostics in text mode instead of failing silently.

diagpick .\fixtures\diag\rust-errors.txt
diagpick .\fixtures\diag\unity-errors.txt --snip --json | ConvertFrom-Json
diagpick .\fixtures\diag\rust-errors.txt --def
diagpick .\BepInEx\LogOutput.log --severity warning

logshape

Collapse repetitive logs into template groups before reading the raw stream.

logshape .\fixtures\logs\repetitive.log
logshape .\fixtures\logs\repetitive.log --json | ConvertFrom-Json | Select-Object -ExpandProperty groups

stringscan

Extract printable strings from binaries or opaque artifacts and classify the high-signal matches.

stringscan .\fixtures\binaries\stringscan-sample.bin
stringscan .\fixtures\binaries\stringscan-sample.bin --details --kind bepinex
fd -a '^stringscan-sample\.bin$' .\fixtures\binaries | stringscan --input-format lines --json | ConvertFrom-Json

toon

Convert between JSON and TOON text, including tabular arrays, safe key folding, safe dotted-path expansion, and JSONL-to-array ingestion.

toon .\fixtures\toon\config.json
toon .\fixtures\toon\config.toon --json | ConvertFrom-Json
toon .\fixtures\toon\records.jsonl

csvshape

Summarize huge CSV or TSV files into a bounded, AI-friendly schema view with detected delimiter, header presence, inferred column kinds, blank counts, short examples, and diff support.

csvshape .\fixtures\csvshape\sample.csv
csvshape .\fixtures\csvshape\sample.tsv --delimiter tab --json | ConvertFrom-Json
csvshape .\fixtures\csvshape\sample.csv --limit-columns 8 --sample-rows 16
csvshape diff .\fixtures\csvshape\sample.csv .\fixtures\csvshape\sample.tsv --json | ConvertFrom-Json

sqliteshape

Inspect SQLite databases read-only without dropping into an interactive shell, keeping the default view cheap and compact, and diff two database shapes when schemas move. Use sqliteshape for SQLite-only local inspection; use sqlshape when you need a normalized cross-database report or diff.

sqliteshape .\fixtures\sqliteshape\sample.db
'C:\data\events.db' | sqliteshape --input-format lines --json | ConvertFrom-Json
sqliteshape .\fixtures\sqliteshape\sample.db --table users --include-indexes
sqliteshape diff .\before.db .\after.db --json | ConvertFrom-Json

sqlshape

Inspect SQL schema shape read-only across PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, and DuckDB. It normalizes tables, views, columns, primary keys, foreign keys, indexes, and cheap row estimates into one model, and it redacts connection strings in reports and errors.

sqlshape --engine sqlite --url .\fixtures\sqliteshape\sample.db --json | ConvertFrom-Json
sqlshape --engine duckdb --url .\data\warehouse.duckdb --toon
sqlshape --engine postgres --url "postgres://user:pass@host:5432/app" --schema public
sqlshape diff --before-engine sqlite --before-url .\before.db --after-engine duckdb --after-url .\after.duckdb --json | ConvertFrom-Json

unityasset

Inspect offline Unity assets, AssetBundles, YAML scenes, and prefabs without opening the Unity editor. Start with index, then use object ids with refs, dump, or extract.

unityasset index 'C:\game\Game_Data'
unityasset index 'C:\game\Game_Data' --class MonoBehaviour --script 'MarketOffer|LaunchVehicle'
unityasset index 'C:\game\Game_Data' --class '^VideoClip$' --summary
unityasset refs 'sharedassets0.assets#1234' 'C:\game\Game_Data' --json | ConvertFrom-Json
unityasset extract 'resources.assets#5678' 'C:\game\Game_Data' --output-dir .\out

unityprobe

Query a running Mono Unity game through an explicit read-only BepInEx bridge. It does not inject implicitly: install the bridge first, check status, then query scenes, objects, instances, or static state.

unityprobe install 'C:\game'
unityprobe status --game-root 'C:\game'
unityprobe --json scenes | ConvertFrom-Json
unityprobe --json find 'Game\.UI\.Windows' | ConvertFrom-Json
unityprobe inspect 10432
unityprobe static Manager.GameManager

unitydiag

Extract high-signal incidents from Unity Player.log and BepInEx logs, with grouping, stack controls, severity filters, and game-root discovery.

unitydiag 'C:\Users\example\AppData\LocalLow\Studio\Game\Player.log'
unitydiag --game-root 'C:\game' --latest
unitydiag 'C:\game\BepInEx\LogOutput.log' --include-info --top 10
unitydiag --game-root 'C:\game' --json | ConvertFrom-Json

envdiff

Capture environment snapshots, compare them, or wrap a command so PATH pollution and variable mutations become obvious immediately.

envdiff snapshot --output .\before.json
envdiff diff .\before.json .\after.json --json | ConvertFrom-Json
envdiff run --shell cmd -- .\scripts\set-env.cmd
envdiff run --shell pwsh -- .\scripts\set-env.ps1

proctree

Show the live Windows process tree, a subtree rooted at a PID, or the descendants of a command you just ran.

proctree system
proctree root 1234 --json | ConvertFrom-Json
proctree run -- pwsh -NoProfile -Command "npm test"

sysshape

Capture a compact machine and tool inventory for AI-friendly triage without manually checking the shell, environment, and language toolchains one by one.

--env safe keeps curated non-secret variables while leaving raw path-like values out of environment; the segmented path_like view carries PATH-heavy details more compactly. JSON output now includes system.default_shell, system.session_shell, path_like[].duplicate_segments, and per-tool probe_status / error.

sysshape --group shell
sysshape --json --env safe --group shell | ConvertFrom-Json
sysshape --json --env safe --group all | ConvertFrom-Json
sysshape --env none --group dev

runprobe

Run one command and capture the stable result object you actually want in scripts or AI flows: exit code, duration, timeout status, and bounded stdout/stderr tails.

runprobe --shell raw -- cmd /d /s /c "exit 0"
runprobe --shell pwsh --timeout 2s -- Write-Output done
runprobe --json --shell cmd --timeout 1s -- cmd /d /s /c "echo hello & echo boom 1>&2 & exit 5" | ConvertFrom-Json

await

Wait for a path, TCP target, HTTP endpoint, or repeated command condition without hand-writing polling loops.

await path .\target\ready.flag --state exists
await port tcp://127.0.0.1:5000 --interval 200ms
await http http://127.0.0.1:8080/health --status 204
await run --shell pwsh -- .\scripts\health.ps1

argv

Quote argument vectors for pwsh/cmd/raw launches and inspect what a shell really passed to a native process.

argv quote --shell pwsh -- git commit -m "two words"
'["tool.exe","two words"]' | argv quote --shell cmd
argv inspect --json --shell pwsh -- alpha "two words" | ConvertFrom-Json

config

Read and edit common config formats with slash-pointer paths and explicit value typing.

config get .\package.json /version
config set .\config.yaml /retries 3 --value-type number
config ls --format toml .\settings.toml --json | ConvertFrom-Json

gitshape

Summarize Git status and diffs into compact AI-friendly counters, changed files, line deltas, and touched-symbol hints.

gitshape status
gitshape status --repo C:\src\repo --json | ConvertFrom-Json
gitshape diff --staged --json | ConvertFrom-Json

reposhape

Detect repository ecosystems, manifests, command entrypoints, and CI hints before you start opening files.

reposhape .
reposhape . --json | ConvertFrom-Json
reposhape C:\src\repo --max-depth 4

dotnetshape

Inspect .NET project graphs, inherited MSBuild properties, package references, and build-shape warnings without invoking MSBuild.

dotnetshape .
dotnetshape . --json | ConvertFrom-Json
dotnetshape C:\src\repo --max-depth 4

unlock

Inspect file lockers and perform unlock-aware delete, move, rename, copy, or free operations with staged escalation. unlock who now defaults to a fast Restart Manager pass for interactive triage, while --deep adds the slower global handle scan when you need exhaustive coverage.

unlock who .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json | Select-Object -ExpandProperty results
unlock who --deep .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json | Select-Object -ExpandProperty results
unlock free --force .\locked.txt
unlock delete --force .\locked.txt

AI Assets

Mercury ships both a compact English AI prompt and a real Codex skill. The prompt is the terse “tool card”; the skill is the route-oriented entrypoint plus the generated command catalog.

pwsh -NoProfile -File .\scripts\generate-ai-prompt.ps1
pwsh -NoProfile -File .\scripts\check-ai-prompt.ps1
pwsh -NoProfile -File .\scripts\generate-ai-skill.ps1
pwsh -NoProfile -File .\scripts\check-ai-skill.ps1

The generated skill lives in .\skills\mercury-toolbox\. Installing into Codex happens when you run install-toolbox.ps1 or install a packaged build, unless -NoCodexSkillInstall is used.

For the authoritative full command reference, prefer the generated assets over this README: docs\ai\mercury-toolbox-ai-prompt.md is the compact prompt view, and skills\mercury-toolbox\references\command-catalog.md is the full generated catalog that packaged installs carry forward too.

Development

For the day-to-day loop, use the repo-level justfile and bacon.toml:

just test and the scoped *-test recipes use cargo nextest; treat nextest as the default test runner for this repository. Plain cargo test is only for tool-specific cases that explicitly require it.

Start new user-facing features from the Jade feature template so CLI contracts, tests, generated AI assets, and handoff notes stay synchronized. For daily low-risk cleanup, use the daily maintenance template with the durable backlog in .codex-progress\quality-security-backlog.md.

just
just --summary
just periphery-check
just workspace-check
just check
just code-check
just data-test
just runtime-check
just windows-test
just msudo-verify
just managed-clippy
just mhash-check
just mhash-test
just mhash-clippy
just mhash-bench
just mhash-benchmark
just ai-check
just test
just install
just uninstall
just package
just install-package
just uninstall-package
just package-roundtrip
just jade-skip-coverage
bacon
bacon code
bacon code-test
bacon code-clippy
bacon data
bacon data-test
bacon data-clippy
bacon mhash
bacon mhash-test
bacon mhash-clippy
bacon runtime
bacon runtime-test
bacon runtime-clippy
bacon windows
bacon msudo-verify
bacon managed
bacon managed-test
bacon managed-clippy
bacon unity-test
bacon unity-clippy
bacon ai
bacon clippy
bacon test

just periphery-check is the lightweight lane for docs, PowerShell scripts, justfile recipes, templates, and generated AI asset hygiene: it prints the recipe summary, runs the PowerShell gate, and rechecks generated AI assets without a Rust rebuild.

just workspace-check is the fast lane for everyday repo-wide confidence: formatting, cargo check, a release-fast workspace build, AI asset checks, and the PowerShell gate without the heavier install/package roundtrips.

For documentation-only maintenance, start from just --summary and the maintainer notes. Add just ai-check when a change mentions generated prompt or skill assets, then use just periphery-check before handoff when the patch changes workflow instructions, templates, scripts, or just recipes. Do not claim generated AI assets were refreshed unless the generator or check command was actually run.

Use the fuller gates when the change reaches beyond that quick lane:

• just ecosystem exercises install, package, and portable install flows.
• just jade is the full mandatory Jade gate: fmt, check, coverage-backed tests, strict Clippy, root and fuzz dependency audits, Miri, fuzzing, sanitizer, no-panic, Loom, PowerShell, generated AI assets, ecosystem checks, and the selected verification build profile.
• just jade-skip-coverage is still a broad local gate, but skipping coverage means it is not the release-quality Jade proof.
• just miri, just fuzz, just sanitizer, just no-panic, and just loom are focused repair loops. They are not exemptions and not a separate optional safety tier.

Run the broader Jade verification gate:

pwsh -NoProfile -File .\scripts\check-jade.ps1

If a hardening gate truly cannot run on a machine, pass the matching -ExemptMiri, -ExemptFuzz, -ExemptSanitizers, -ExemptNoPanic, or -ExemptLoom flag with a non-empty reviewed reason. Do not turn those exemptions into default workflow recipes.

Run the install/package ecosystem gate:

pwsh -NoProfile -File .\scripts\check-ecosystem.ps1

The hosted Gitea repository now uses native .gitea/workflows automation:

• .gitea/workflows/ci.yml runs the everyday verification lane on pushes, pull requests, and manual dispatches.
• .gitea/workflows/release.yml is tag-driven. It requires a tag like v0.1.0 that matches [workspace.package].version, runs just jade, builds the portable package, and publishes the release through scripts\publish-gitea-release.ps1.
• scripts\setup-gitea-runner.ps1 provisions a Windows host runner for the current repo, registers it with the repo-level runner token API, writes a host-backend config, and installs a startup entry so .gitea/workflows can execute on this machine again after logon.

For runner or release maintenance, keep the toolchain snapshot and secret surfaces in the handoff: confirm cargo nextest --version, cargo llvm-cov --version, just --version, and pwsh --version are visible in CI logs, and treat .runner, GITEA_TOKEN, and GITEA_API_TOKEN as host-local secret material. The maintainer checklist for those flows lives in docs/maintainer-notes.md.

If Git for Windows crashes in git-remote-https.exe while credential-manager or schannel credentials are being resolved, do not embed tokens in origin or Git config. Use the repo helper, which disables credential-manager lookup for that one command and passes a transient Basic auth header:

$env:GITEA_API_TOKEN = '<repo token for this shell only>'
pwsh -NoProfile -File .\scripts\invoke-gitea-git.ps1 ls-remote origin refs/heads/main
pwsh -NoProfile -File .\scripts\invoke-gitea-git.ps1 push origin main

The helper uses Git's OpenSSL backend by default and keeps TLS verification enabled. If the local Gitea test host is temporarily presenting a certificate chain that Git cannot validate, add -InsecureSkipTlsVerify only for that one command. See docs\maintainer-notes.md before changing machine-wide Git credential or TLS settings.

For a local one-shot release from a checked-out repo, the just recipes now line up with the hosted workflow:

just package
just publish-release v0.1.0 .\docs\releases\v0.1.0.md

Measure binary size and representative latency with the probe gate:

pwsh -NoProfile -File .\scripts\probe-toolbox.ps1
pwsh -NoProfile -File .\scripts\probe-toolbox.ps1 -BuildProfile ReleaseSize -SkipBenchmarks
pwsh -NoProfile -File .\scripts\probe-toolbox.ps1 -BuildProfile ReleaseFast -IncludeBloat

On Windows, cargo flamegraph will use DTrace when it is configured; otherwise it falls back to blondie, which requires an elevated shell. probe-toolbox.ps1 -IncludeFlamegraph writes a capability report first and skips impossible runs instead of repeatedly failing blindly.

samply is installed by the Jade tooling script, but Windows recording still requires xperf.exe from Windows Performance Toolkit.

sccache is also wired into .cargo/config.toml as the default rustc-wrapper. Check it with sccache --show-stats, and reset counters with sccache --zero-stats before a fresh probe run when you want clean measurements.

For a one-shot UAC relay on Windows, use the dedicated wrapper:

pwsh -NoProfile -File .\scripts\cargo-flamegraph-windows.ps1 -Package refs -TargetArgumentJson '["helper",".\\fixtures\\polyglot\\repo","--limit","12"]'

If you add -LogPath .\dist\probe\release-fast\flamegraphs\refs.log, the wrapper now writes a compact relay log to refs.log and the full elevated-session transcript to refs.log.transcript.txt.