MercuryToolbox/docs/ai/mercury-toolbox-ai-prompt.md

Mercury Toolbox AI Prompt

Available tools: cjson, ison, isonl, zon, tonl, mhash, jsonlgrep, jsonshape, 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 Rules: Prefer Mercury first when the task is local inspection, shaping, or triage. Prefer compact text. Use --json when the next step parses output, and use --toon or --format toon when structured output is meant for an AI/model to read. Pipe external JSON into toon only when the producer is not a Mercury tool; TOON auto-detects JSON and emits denser TOON by default. Set $env:MERCURY_OUTPUT='json' or $env:MERCURY_OUTPUT='toon' when most commands in the session should default to that structured format. Prefer stdin and pipelines over re-reading large files. Prefer fileprobe, outline, snip, chunkcat, hitsnip, defsnip, codeshape, refs, and ctxpack over raw Get-Content, cat, or whole-file dumps. Every tool has guided triage metadata in the generated prompt and skill catalog; PE deep-analysis tools also emit runtime answer=, trust, report_quality, and next_actions fields. For every command, read the generated guided_triage answer, trust basis, and next actions before inventing a new path. When you are unsure which command to run next, prefer the emitted next_actions before inventing an ad-hoc pipeline. Use these tools with modern CLI companions such as rg, fd, jq, yq, bat, sd, xh, tokei, eza, procs, dust, hyperfine, hexyl, zoxide, lazygit, delta, and PowerShell. Prefer mhash for local hashing, OpenHashTab-class algorithm discovery, JSONL manifest generation and verification, and quick hash throughput benches; pair its JSON/JSONL output with jq and compare external command timing with hyperfine when needed. Prefer rg over recursive grep or Select-String, fd over recursive Get-ChildItem, bat over raw Get-Content, jq or yq over manual JSON or YAML parsing, and xh over curl for quick HTTP checks. cjson: Compact JSON or JSONL before piping, diffing, or model input. Better than: pretty multi-line JSON when you need compact stable output and optional key sorting. Usage: cjson [OPTIONS] [PATH] Example: cjson <PATH> Guided: answer=Answer whether JSON/JSONL can be compacted cleanly and deterministically. trust=Trust the JSON parser result and document count; invalid JSON is reported before compaction. next=Run jsonshape on the compacted payload when you need schema shape. | Pipe to jq or toon for projection/model handoff. ison: Convert between JSON and ISON records for compact structured handoff. Better than: verbose JSON when a deterministic compact ISON representation is easier to scan or diff. Usage: ison [OPTIONS] [PATH] Example: ison <PATH> Guided: answer=Answer whether JSON can round-trip through compact ISON for handoff. trust=Trust successful parser/encoder output; use JSON mode when a tool must consume it next. next=Use isonl for line-oriented streams. | Use toon when the next consumer is an AI model. isonl: Convert between JSONL and ISONL line records. Better than: manual JSONL splitting when line-oriented ISON records are better for streaming or model input. Usage: isonl [OPTIONS] [PATH] Example: isonl --from jsonl --to isonl <PATH> Guided: answer=Answer whether JSONL/ISONL records can be converted as a stream. trust=Trust per-line parser diagnostics and document counts; malformed lines stop the conversion. next=Pipe into jsonlgrep for filtering. | Use cjson or toon for downstream compact handoff. zon: Convert JSON or JSONL to Zero Overhead Notation and back. Better than: hand-written compact table encodings when you need Zero Overhead Notation interop without Node tooling. Usage: zon [OPTIONS] [PATH] Example: zon <PATH> Guided: answer=Answer whether JSON/JSONL can convert to or from Zero Overhead Notation. trust=Trust parser diagnostics and wrapper metadata for document count and target format. next=Use jsonshape after decoding to validate shape. | Use toon for model-facing structured summaries. tonl: Encode, decode, query, validate, index, stream-query, and ETL JSON-backed TONL data. Better than: one-off scripts for compact JSON ETL, validation, query, indexing, or streaming filters. Usage: tonl <COMMAND> [OPTIONS] [PATH] | tonl index <build|query> [OPTIONS] | tonl stream query [OPTIONS] [PATH] Example: tonl query --where active=true <PATH> Guided: answer=Answer filtered TONL records, validation status, indexes, or ETL conversion results. trust=Trust explicit validation/query diagnostics; streaming mode reports record-level failures. next=Use jsonlgrep for simple JSONL filtering before TONL conversion. | Use cjson or toon for compact handoff. mhash: Compute local file hashes across the OpenHashTab-class matrix, list algorithms, hash with --all or explicit multi-algorithm sets, produce JSONL manifests, verify manifests, or benchmark hash throughput. Better than: PowerShell Get-FileHash loops, GUI hash tabs, ad-hoc checksum scripts, or manual benchmark harnesses when you need OpenHashTab-class algorithm coverage, manifests, verification, JSON/JSONL, and throughput telemetry in one local CLI. Usage: mhash [OPTIONS] [PATH...] | mhash verify [OPTIONS] <MANIFEST> | mhash list-algorithms [--json] | mhash bench [OPTIONS] [PATH...] Example: mhash --algorithm sha256,blake3-256,xxh3-128 .\dist\MercuryToolbox.zip --json | ConvertFrom-Json Guided: answer=Answer file identity, checksum, manifest verification, or hash throughput questions. trust=Trust algorithm labels, manifest verification status, and per-file error rows. next=Use fileprobe first when the file type is unknown. | Use jsonlgrep or jq to filter manifest rows. jsonlgrep: Filter JSONL logs, single-line JSON arrays, or structured event streams by field. Better than: ad-hoc jq for simple field filters, projections, counts, and regex matches. Usage: jsonlgrep [OPTIONS] <QUERY> [PATH...] Example: recent --root . --limit 20 --json | jsonlgrep 'path~=LogOutput' --pick modified_rfc3339,path --json | ConvertFrom-Json Guided: answer=Answer which JSONL records match field, regex, or projection filters. trust=Trust parsed JSON records and explicit malformed-line diagnostics. next=Use jsonshape on matched records to inspect structure. | Use toon or cjson for compact AI handoff. jsonshape: Summarize JSON or JSONL into path/type stats, or diff two shape reports. Better than: opening raw payloads when you first need the shape, key paths, or a schema diff. Usage: jsonshape [OPTIONS] [PATH...] | jsonshape [OPTIONS] diff <BEFORE> <AFTER> Example: jsonshape diff before.json after.json --json | ConvertFrom-Json Guided: answer=Answer the key paths, types, counts, and shape differences in JSON/JSONL. trust=Trust reported path/type counts when parsing succeeds; review diff diagnostics for drift. next=Use jsonlgrep to isolate records before reshaping. | Use cjson to normalize payloads before comparing. recent: List recently changed files or directories. Better than: manual directory scans when you just need the freshest files and .gitignore awareness. Usage: recent [OPTIONS] Example: recent --root . --since 2h --ext rs --name '^(lib|main)$' Guided: answer=Answer which files or directories changed recently. trust=Trust timestamp filters and gitignore-aware discovery within the selected root. next=Pipe paths into fileprobe or outline. | Use hitsnip or ctxpack after narrowing files. pathshadow: Show which executable wins and which ones are shadowed. Better than: guessing PATH order when the wrong executable is being picked. Usage: pathshadow [OPTIONS] [COMMAND...] Example: pathshadow python npm --shell powershell --summary --json | ConvertFrom-Json Guided: answer=Answer which executable wins on PATH and which candidates are shadowed. trust=Trust resolved filesystem candidates and shell-aware summary rows. next=Use sysshape --group shell for broader environment context. | Use argv quote when command invocation quoting is suspicious. portping: Probe ports or health endpoints with timings. Better than: jumping between multiple network tools for quick TCP and HTTP reachability checks. Usage: portping [OPTIONS] [TARGET...] Example: portping tcp://127.0.0.1:80 Guided: answer=Answer whether a TCP/HTTP/HTTPS endpoint is reachable and how long it took. trust=Trust direct connection/status timing; failures distinguish DNS, connect, and HTTP states. next=Use portunlock when a local port is unexpectedly occupied. | Use await port/http to wait for readiness. portunlock: Show and free local TCP or UDP port owners on Windows. Better than: guessing which process owns a port or hand-writing netstat and kill loops when a local listener refuses to go away. Usage: portunlock [OPTIONS] who <PORT...> | portunlock [OPTIONS] free <PORT...> Example: portunlock who --json --protocol any 3000 8080 | ConvertFrom-Json Guided: answer=Answer which process owns a local TCP/UDP port and optionally free it. trust=Trust OS port snapshots and post-action verification rows. next=Use proctree on the owning PID before freeing. | Use portping after freeing or restarting a listener. msudo: Top-level high-risk command: inspect Windows elevation relay status, token state, active session state, and host availability before any privileged launch. Better than: guessing whether Windows elevation relay support is available, or hand-writing Start-Process -Verb RunAs wrappers when you first need the current privilege status. Usage: msudo [OPTIONS] [--] <COMMAND...> | msudo run [OPTIONS] [--] <COMMAND...> | msudo status [OPTIONS] | msudo [OPTIONS] --shell <PRESET> Example: msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated Guided: answer=Answer Windows elevation, token, relay, and launch-shape questions. trust=Trust status discovery before launch; treat run actions as high risk and explicit. next=Start with msudo status --json. | Use argv quote before privileged shell wrapping. asmtype: List managed assembly types and filter them by name, namespace, base type, interface, or matching members, with optional user-code-only screening. Better than: manual reflection or ad-hoc PowerShell when you first need the type map from a managed assembly. Usage: asmtype [OPTIONS] [ASSEMBLY...] Example: asmtype <PATH> --with-member-match 'Build|Launch' --show-matched-members --pick full_name,base_type,matched_members --json | ConvertFrom-Json Guided: answer=Answer which managed types match name, inheritance, interface, or member intent. trust=Trust metadata enumeration from the target assembly; broaden filters when no matches return. next=Pipe JSONL into asmmember. | Use asmflow find/xref when behavior matters. asmmember: Inspect managed type members with binding filters and compact signatures, including JSONL handoff from asmtype and user-code-only filtering. Better than: long reflection scripts when you need methods, fields, and properties from a known managed type. Usage: asmmember [OPTIONS] <TYPE...> Example: asmtype <PATH> --intent unity-spacecraft-workflow --json | asmmember --assembly <PATH> --input-format jsonl --intent unity-spacecraft-workflow --pick type_name,name,visibility,signature --json | ConvertFrom-Json Guided: answer=Answer which methods, fields, and properties exist on selected managed types. trust=Trust assembly metadata and binding filters; use non-public filters intentionally. next=Use asmflow body for IL details. | Use asmapi diff when comparing versions. asmref: Inspect managed assembly references, check whether they resolve from local directories, or run diagnose to report closure risks such as missing references, same-name version/token conflicts, winning DLLs, test-only leaks, and obvious MissingMethod/TypeLoad hazards. Better than: guessing missing managed dependencies when you need a fast reference, resolution, or Unity/Rocket plugin closure diagnosis pass. Usage: asmref [OPTIONS] [ASSEMBLY...] | asmref diagnose [OPTIONS] [ASSEMBLY...] Example: asmref diagnose <PATH> --resolve-dir <PATH> --format toon Guided: answer=Answer managed references, resolution status, and dependency closure risks. trust=Trust resolved candidates and risk tiers; explicit resolve dirs define the runtime universe. next=Run asmref diagnose for closure risks. | Use asmapi diff on risky version changes. asmapi: Compare two managed assemblies for added or removed public types, removed methods, signature changes, and MissingMethodException risks, with optional internal/all visibility. Better than: manual reflection diffs or brittle spreadsheet comparisons when you need to know what managed API changed between two DLL versions. Usage: asmapi [OPTIONS] <SUBCOMMAND> [ARGS...] Example: asmapi diff .\old\0Harmony.dll .\new\0Harmony.dll --json | ConvertFrom-Json Guided: answer=Answer public API differences between managed assemblies. trust=Trust metadata comparison under the chosen visibility scope. next=Use asmref diagnose to connect API drift to dependency closure. | Use asmmember on removed or changed types. asmflow: Inspect managed method bodies, IL summaries, and cross-references for Unity and general .NET reverse-engineering flows. Better than: ad-hoc IL dump scripts or manual dnSpy browsing when you need callers, callees, field access, or string literals from a managed method quickly. Usage: asmflow [OPTIONS] <SUBCOMMAND> [ARGS...] Example: asmflow xref --assembly <PATH> 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartProject' --json | ConvertFrom-Json Guided: answer=Answer managed IL bodies, callers, callees, field access, and string references. trust=Trust method-body metadata when the target method resolves; unknown bodies are reported. next=Use asmtype/asmmember to find exact targets. | Use ctxpack to hand off IL evidence. llvmobjdump: Inspect object sections, symbol labels, and disassembly through LLVM backend discovery. Better than: raw llvm-objdump text when you need compact section, symbol, and disassembly shape for COFF/PE or object files. Usage: llvmobjdump [OPTIONS] [PATH...] Example: llvmobjdump .\target\release-fast\binmeta.exe --json | ConvertFrom-Json Guided: answer=Answer object sections, symbols, and disassembly shape through LLVM. trust=Trust LLVM backend output plus parser warnings/raw blocks for unsupported regions. next=Use llvmreadobj for headers/imports/debug hints. | Use pecalls or pesig for PE-focused call/function triage. llvmreadobj: Inspect COFF/PE headers, sections, imports, exports, and debug hints through LLVM backend discovery. Better than: heavy binary viewers or raw llvm-readobj output when you need a bounded COFF/PE header, import/export, and debug/PDB summary. Usage: llvmreadobj [OPTIONS] [PATH...] Example: llvmreadobj .\target\release-fast\binmeta.exe --json | ConvertFrom-Json Guided: answer=Answer COFF/PE headers, sections, imports, exports, and debug hints through LLVM. trust=Trust LLVM backend exit status and parsed blocks; raw blocks preserve unparsed details. next=Use peimports/peexports for PE-focused grouping. | Use llvmobjdump when code layout or disassembly is needed. llvmnm: List and classify object symbols through LLVM nm output. Better than: raw symbol-table dumps when you need stable symbol rows with kind, address, size, object/archive prefix, and source-line hints. Usage: llvmnm [OPTIONS] [PATH...] Example: llvmnm .\target\release-fast\binmeta.exe --defined-only --json | ConvertFrom-Json Guided: answer=Answer defined/undefined symbols with stable LLVM nm rows. trust=Trust POSIX-format symbol parsing and backend stderr tails. next=Use llvmobjdump for disassembly around symbols. | Use llvmreadobj for object headers and debug hints. peexports: Inspect export surfaces, spot forwarded symbols, filter by name or ordinal, and use report_quality/next_actions to decide the next PE pass. Better than: manual PE export-table browsing when you want names, ordinals, RVA/VA, forwarders, and guided follow-up commands without opening a heavy PE debugger. Usage: peexports [OPTIONS] [PATH...] Example: peexports C:\Windows\System32\kernel32.dll --forwarders-only --json | ConvertFrom-Json Guided: answer=Answer PE export names, ordinals, RVAs/VAs, forwarders, and entrypoint hints. trust=Trust PE export table parsing plus report_quality evidence and limitations. next=Use peimports to inspect dependencies. | Use llvmreadobj --exports to cross-check LLVM output. peimports: Inspect imports by library, name, or category, quickly separate filesystem, registry, device I/O, NT, and network APIs, then follow emitted next_actions. Better than: ad-hoc import-table triage when you need API families grouped into human-friendly categories with immediate callsite and role follow-ups. Usage: peimports [OPTIONS] [PATH...] Example: peimports .\target\release-fast\portping.exe --category device_io --json | ConvertFrom-Json Guided: answer=Answer imported APIs grouped by library and API category. trust=Trust PE import table parsing plus report_quality evidence and limitations. next=Use pecalls on interesting categories. | Use drvshape for driver-like/native profiles. pecalls: Extract callsites for one or more imported APIs or API categories from LLVM objdump text and inspect report_quality.limitations before treating it as exhaustive. Better than: guessing import callsites from raw disassembly when you want direct IAT matches plus trust metadata around best-effort disassembly parsing. Usage: pecalls [OPTIONS] [PATH...] Example: pecalls .\target\release-fast\portping.exe --api WSAStartup --json | ConvertFrom-Json Guided: answer=Answer direct imported API callsites found through LLVM disassembly. trust=Trust direct IAT-target matches; report_quality limitations mark disassembly truncation or gaps. next=Use peimports to choose categories. | Use pesig to place callsites inside functions. pesig: Infer function boundaries, source hints, and calling conventions from PE text and metadata, then pivot to imports, callsites, or raw objdump via next_actions. Better than: manual function-boundary and calling-convention inference when you need a quick v1 signal with explicit confidence and next-step context. Usage: pesig [OPTIONS] [PATH...] Example: pesig .\target\release-fast\portping.exe --min-confidence medium --json | ConvertFrom-Json Guided: answer=Answer likely PE function boundaries and calling-convention hints. trust=Trust confidence/evidence per function and report_quality for parse completeness. next=Use pecalls to connect functions to APIs. | Use llvmobjdump for raw disassembly context. pestrrefs: Scan ASCII or UTF-16LE strings, report direct references from LLVM disassembly, and use next_actions to connect strings to imports, callsites, or IOCTL constants. Better than: opening a disassembler and a string viewer separately when you need string hits with direct xrefs and a clear next triage command. Usage: pestrrefs [OPTIONS] [PATH...] Example: pestrrefs .\target\release-fast\portping.exe --contains DeviceIoControl --json | ConvertFrom-Json Guided: answer=Answer strings and direct code references in PE files. trust=Trust direct VA/range xrefs; unresolved counts are not guessed. next=Use peimports to connect strings to APIs. | Use ioctlscan for device-control constants. drvshape: Summarize likely WDM, KMDF, NDIS, minifilter, or native driver traits, surface heuristic driver hints, and treat report_quality as the trust boundary. Better than: guessing the driver role from imports and exports when you want a compact Windows driver profile with IOCTL/import/callsite follow-ups already suggested. Usage: drvshape [OPTIONS] [PATH...] Example: drvshape C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json Guided: answer=Answer likely Windows driver role, subsystem, imports, exports, and heuristic hints. trust=Trust role hints as heuristics, not vulnerability conclusions; report_quality shows evidence. next=Use ioctlscan to decode CTL_CODE candidates. | Use pecalls --category device_io for dispatch/callsite evidence. ioctlscan: Scan PE bytes and disassembly-adjacent data for likely IOCTL constants, decode their fields, and use report_quality to separate strong hits from heuristic candidates. Better than: searching for Windows IOCTL constants by hand when you want decoded CTL_CODE fields, code locations, and suggested role/callsite/string follow-ups. Usage: ioctlscan [OPTIONS] [PATH...] Example: ioctlscan C:\Windows\System32\drivers\ndis.sys --json | ConvertFrom-Json Guided: answer=Answer probable IOCTL constants and decoded CTL_CODE fields. trust=Trust confidence/evidence per candidate; raw byte hits are heuristic until tied to code context. next=Use drvshape to confirm driver role. | Use pestrrefs or pecalls for surrounding evidence. binmeta: Inspect file metadata, Windows PE basics, version/company/product identity, embedded Authenticode certificate tables, WinTrust status, catalog signing, signer certificate subjects, chains, timestamps, and expiry hints. Better than: opening heavy PE tooling or shelling out to signature utilities when you first need binary identity, PE basics, version resources, and Windows signing status. Usage: binmeta [OPTIONS] [PATH...] Example: binmeta .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json Guided: answer=Answer file identity, PE basics, version resource fields, company/product names, signature status, embedded-vs-catalog signing, signer subject, certificate chain, timestamp, and expiry fields before deeper binary analysis. trust=Trust goblin PE/resource parsing for local structure and Windows WinTrust/catalog status on Windows; signature failures are reported as metadata, not command failures. On non-Windows, trust only embedded certificate table presence and treat WinTrust fields as unsupported. next=Use peimports or llvmreadobj for deeper PE detail after identity is known. | Use drvshape or ioctlscan for signed drivers and native/system binaries. | Use stringscan or pestrrefs when identity/version metadata is missing or suspicious. fileprobe: Classify files as text, binary, generated, minified, test, vendor, and more, including encoding, BOM, and newline diagnostics. Better than: blindly opening files when you need a fast read-worthiness, encoding, or newline check first. Usage: fileprobe [OPTIONS] [PATH...] Example: fileprobe .\src\main.rs Guided: answer=Answer whether a path is text, binary, generated, minified, vendor, or worth opening. trust=Trust bounded sniffing, encoding, newline, and classification diagnostics. next=Use outline or chunkcat for readable text. | Use binmeta or stringscan for binary files. outline: List top-level code or config structure. Better than: scrolling whole files when you only need the structure. Usage: outline [OPTIONS] <PATH...> Example: outline <PATH> Guided: answer=Answer top-level structure of source or config files. trust=Trust parser-supported outlines and explicit unsupported-file diagnostics. next=Use defsnip for exact definitions. | Use refs or codeshape for broader symbol maps. codeshape: Map a codebase into files plus AST-backed declarations and signatures from the shared codeindex engine. Better than: plain tree output when you need internal declarations and signatures without dumping full source files. Usage: codeshape [OPTIONS] [PATH...] Example: codeshape --max-depth 1 --limit-per-file 8 . --json | ConvertFrom-Json Guided: answer=Answer repository file/declaration shape with AST-backed summaries. trust=Trust codeindex parser results and skipped-file diagnostics. next=Use defsnip to extract definitions. | Use refs to find use sites. refs: Find exact symbol references or caller definitions through the shared codeindex engine with text fallback. Better than: falling back to raw rg when you need exact use-sites or caller summaries for a known symbol. Usage: refs [OPTIONS] <SYMBOL> [PATH...] | refs [OPTIONS] --at <PATH:LINE[:COL]> [PATH...] Example: refs helper <PATH> Guided: answer=Answer symbol references or callers across source files. trust=Trust codeindex hits and caller grouping under the selected roots. next=Use hitsnip to expand hit context. | Use defsnip for definition bodies. snip: Extract precise snippets from files or stdin. Better than: dumping whole files when you only need exact lines, matches, or symbols. Usage: snip [OPTIONS] [PATH...] Example: snip --lines 16:27 <PATH> Guided: answer=Answer exact bounded source/text snippets by line, match, or symbol. trust=Trust line numbers and bounded extraction; binary or missing paths are rejected. next=Use hitsnip after rg for multiple hits. | Use ctxpack to bundle snippets. defsnip: Extract full AST-backed definitions by exact symbol name through the shared codeindex engine. Better than: line-number snippets when you need the full function, class, or method body even after nearby edits move the lines. Usage: defsnip [OPTIONS] <SYMBOL> [PATH...] Example: defsnip build_report . --json | ConvertFrom-Json Guided: answer=Answer full AST-backed definition blocks for symbols. trust=Trust codeindex definitions and language support; no match means broaden symbol/root. next=Use refs for callers/use sites. | Use ctxpack to package the definition with nearby context. ctxpack: Pack files, snippets, hits, diagnostics, or definition JSON into compact context blocks. Better than: hand-assembling ad-hoc prompt context from files, hits, diagnostics, and definitions. Usage: ctxpack [OPTIONS] [INPUT...] Example: ctxpack <PATH> Guided: answer=Answer compact prompt-ready context from files, snippets, hits, and diagnostics. trust=Trust included path and byte/line caps; review omitted/truncated sections for scope. next=Use fileprobe/codeshape before packing broad roots. | Use diagpick or hitsnip to feed focused evidence. chunkcat: Read large text files in bounded chunks, including quick tail-style log windows. Better than: huge file dumps when you need deterministic windows. Usage: chunkcat [OPTIONS] [PATH...] Example: chunkcat .\BepInEx\LogOutput.log --max-lines 20 --tail Guided: answer=Answer a bounded chunk or inventory of a large text file. trust=Trust chunk indices, line ranges, and binary detection. next=Use snip when you know the exact line range. | Use hitsnip to expand search hits into chunks. hitsnip: Turn search hits into compact snippets or promote them to enclosing definitions. Better than: raw rg hit lists when you need merged readable context or the enclosing definition instead of a tiny window. Usage: hitsnip [OPTIONS] [HIT...] Example: rg -nH "helper" <PATH> | hitsnip --def Guided: answer=Answer merged snippets around rg-style search hits. trust=Trust hit parsing and merge ranges; malformed hit lines are reported. next=Use rg -nH to feed hits. | Use defsnip when the hit is inside a known symbol. diagpick: Extract compiler or runtime diagnostics from noisy logs, with optional snippets and enclosing definitions. Better than: reading full logs when you need the actionable errors first and want direct source or definition context. Usage: diagpick [OPTIONS] [PATH...] Example: diagpick <PATH> --def Guided: answer=Answer actionable diagnostics extracted from compiler/build/log text. trust=Trust recognized diagnostic formats and preserved source context. next=Use snip on referenced files/lines. | Use runprobe to capture the failing command reproducibly. logshape: Group recurring log lines into templates. Better than: reading repetitive logs line by line when you need the dominant patterns. Usage: logshape [OPTIONS] [PATH...] Example: logshape <PATH> Guided: answer=Answer repeated log templates, incidents, and message clusters. trust=Trust grouping counts and examples; rare lines may stay as individual templates. next=Use diagpick for actionable errors. | Use jsonlgrep when logs are structured JSONL. stringscan: Extract and classify high-signal strings from binaries or blobs. Better than: a full reverse-engineering pass when you first need identity clues from strings. Usage: stringscan [OPTIONS] [PATH...] Example: stringscan <PATH> Guided: answer=Answer strings and classified hints from arbitrary blobs. trust=Trust extracted string offsets and classification labels; encoding limits are explicit. next=Use binmeta first for binary identity. | Use pestrrefs for PE strings with xrefs. toon: Convert between JSON and TOON. Better than: verbose JSON when you want a denser structured text form. Usage: toon [OPTIONS] [PATH] Example: '{"ok":true}' | toon Guided: answer=Answer compact model-readable TOON from JSON/JSONL or decode TOON back. trust=Trust parser/encoder diagnostics and document wrapper metadata. next=Use native --toon on Mercury producers when available. | Use cjson/jsonshape before converting questionable JSON. csvshape: Summarize large CSV or TSV files into compact schema/bounded stats, or diff two CSV shapes. Better than: opening huge CSV or TSV files when you first need the columns, rough types, blanks, example values, or a shape diff. Usage: csvshape [OPTIONS] [PATH...] | csvshape [OPTIONS] diff <BEFORE> <AFTER> Example: csvshape diff before.csv after.csv --json | ConvertFrom-Json Guided: answer=Answer CSV/TSV delimiter, columns, row counts, and schema differences. trust=Trust parsed rows under the detected or requested delimiter. next=Use jsonshape after converting CSV to JSON externally. | Use config or sqlshape when CSV describes configuration/data imports. sqliteshape: Inspect SQLite databases read-only with compact schema/table summaries, or diff two SQLite shapes. Better than: dropping into an interactive SQLite shell when you only need schema, sample rows, light table stats, or a shape diff. Usage: sqliteshape [OPTIONS] [PATH...] | sqliteshape [OPTIONS] diff <BEFORE> <AFTER> Example: 'C:\data\events.db' | sqliteshape --input-format lines --json | ConvertFrom-Json Guided: answer=Answer SQLite tables, columns, indexes, triggers, and schema diffs. trust=Trust SQLite catalog queries against the selected database file. next=Use sqlshape for normalized cross-engine reports. | Use jsonshape/csvshape on exported data samples. sqlshape: Inspect PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, or DuckDB schemas read-only with redacted connection sources and normalized cross-engine diffs. Better than: hand-writing per-engine catalog queries or exposing raw connection strings when you need a normalized cross-database schema report or diff. Usage: sqlshape [OPTIONS] --url <CONNECTION> | sqlshape [OPTIONS] diff --before-url <CONNECTION> --after-url <CONNECTION> Example: sqlshape --engine sqlite --url <PATH> --json | ConvertFrom-Json Guided: answer=Answer normalized SQL schema across SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, or DuckDB. trust=Trust engine-specific introspection and redacted connection reporting. next=Use sqliteshape for SQLite-specific detail. | Use config to inspect connection/config files safely. unityasset: Inspect Unity serialized assets, bundles, and YAML objects, then trace refs, dump fields, or extract payloads such as TextAsset, MonoScript, AudioClip, and VideoClip. Better than: opening a heavy Unity GUI tool when you first need an index, object refs, field dump, or a quick extraction path for assets, scripts, audio, or video. Usage: unityasset [OPTIONS] index [PATH...] | unityasset [OPTIONS] refs <OBJECT_ID> [PATH...] | unityasset [OPTIONS] dump <OBJECT_ID> [PATH...] | unityasset [OPTIONS] extract <OBJECT_ID> [PATH...] [--output-dir <DIR>] Example: unityasset index 'C:\game\Game_Data' Guided: answer=Answer Unity asset indexes, object dumps, references, and extraction writes. trust=Trust parsed serialized files/bundles and explicit unresolved reference rows. next=Use unitydiag for runtime/log symptoms. | Use asmtype/asmflow for managed script assemblies. unityprobe: Install and query a read-only BepInEx bridge for live scenes, objects, and static state in a running Mono Unity game on Windows. Better than: hand-writing BepInEx reflection plugins or one-off named-pipe helpers when you only need a read-only runtime snapshot from a Mono Unity game. Usage: unityprobe [OPTIONS] <SUBCOMMAND> [ARGS...] Example: unityprobe install 'C:\game' Guided: answer=Answer read-only Unity runtime bridge status, object search, and inspection. trust=Trust explicit bridge install/status and Windows named-pipe reachability. next=Use unitydiag when runtime logs explain bridge issues. | Use unityasset for offline assets. unitydiag: Summarize Unity Player.log and BepInEx logs into grouped incidents, normalized messages, and domain-aware failure summaries. Better than: reading raw Player.log and BepInEx logs end to end when you need the repeated incidents, top frames, and mod-vs-framework blame split first. Usage: unitydiag [OPTIONS] [PATH...] Example: unitydiag 'C:\Users\example\AppData\LocalLow\Studio\Game\Player.log' Guided: answer=Answer Unity/BepInEx log incidents, grouped frames, and mod/runtime warnings. trust=Trust discovered log paths, grouping counts, and preserved stack snippets. next=Use asmref diagnose for plugin dependency issues. | Use unityprobe when live object state is needed. envdiff: Snapshot, diff, or run commands while reporting environment-variable changes. Better than: hand-comparing environment variables before and after a script, especially around PATH pollution and batch wrappers. Usage: envdiff [OPTIONS] run --shell cmd|pwsh|raw -- <COMMAND...> Example: envdiff run --shell cmd -- .\scripts\set-env.cmd Guided: answer=Answer environment variable changes before/after a command or between snapshots. trust=Trust captured before/after maps and PATH segment deltas. next=Use pathshadow after PATH changes. | Use sysshape for broader shell/tool inventory. proctree: Inspect whole-system, rooted, matched, or command-run Windows process trees in AI-friendly form; use --match to filter by image name or command line. Better than: flat process lists when you need parent-child context, short command lines, and lingering orphan hints. Usage: proctree [OPTIONS] system|root <PID>|run -- <COMMAND...> Example: proctree system --match 'pwsh|Mercury' --include-cmdline Guided: answer=Answer process trees, rooted processes, and command ancestry. trust=Trust OS process snapshots at capture time; short-lived processes may disappear. next=Use portunlock for port owners. | Use runprobe to capture command execution shape. sysshape: Capture a compact local system and tool inventory for AI-friendly triage, including shell hints, path-like duplication, and probe status. Better than: asking users ad-hoc setup questions or checking versions one tool at a time when you need a compact local machine inventory first. Usage: sysshape [OPTIONS] Example: sysshape --json --env safe --group shell | ConvertFrom-Json Guided: answer=Answer machine, shell, environment, and tool inventory shape. trust=Trust detected command paths/versions and grouped environment metadata. next=Use pathshadow for a specific executable winner. | Use envdiff around commands that mutate the environment. runprobe: Run one command and capture exit code, duration, timeout status, and bounded output tails. Better than: reading fragile shell text when what you really need is the stable result object for one command run. Usage: runprobe [OPTIONS] -- <COMMAND...> Example: runprobe --shell raw -- cmd /d /s /c "exit 0" Guided: answer=Answer command exit code, duration, stdout/stderr tails, and timeout behavior. trust=Trust captured process result and bounded output tails. next=Use diagpick on captured stderr/stdout. | Use envdiff run when environment mutation matters. await: Wait for a path, TCP target, HTTP endpoint, or command condition with bounded polling. Better than: writing ad-hoc polling loops for files, ports, HTTP endpoints, or repeat-until-success commands. Usage: await [OPTIONS] path <PATH> [--state exists|missing] | await [OPTIONS] port <TARGET> | await [OPTIONS] http <URL> [--status <CODE>] | await [OPTIONS] run [--shell <MODE>] [--cwd <PATH>] [--exit-code <CODE>] [--tail-bytes <COUNT>] -- <COMMAND...> Example: await path .\target\ready.flag Guided: answer=Answer whether a path, port, HTTP endpoint, or command became ready before timeout. trust=Trust polling attempts, final state, and timeout status. next=Use portping for one-shot endpoint detail. | Use runprobe for command readiness probes. argv: Quote argv for pwsh or cmd, or inspect what a shell actually passed to a native process. Better than: guessing how PowerShell or cmd really passed arguments to a native process. Usage: argv quote --shell <pwsh|cmd|raw> [VALUE...] | argv inspect [--json] --shell <pwsh|cmd|raw> [VALUE...] Example: argv quote --shell pwsh -- git commit -m "two words" Guided: answer=Answer how arguments should be quoted or how a shell actually passes them. trust=Trust helper round-trips for the selected shell/platform. next=Use runprobe to execute the quoted command. | Use msudo status before privileged shell wrapping. config: Read, inspect, list, set, or delete config values in JSON, YAML, TOML, env, and INI files. Better than: fighting jq or hand-editing config files when you need safe slash-pointer reads or edits across common formats. Usage: config [OPTIONS] [PATH] | config [OPTIONS] <get|inspect|ls|set|delete> <PATH> [POINTER] [VALUE] Example: config get .\package.json /version Guided: answer=Answer get/set/delete operations over JSON/YAML/TOML/env/INI config paths. trust=Trust parser-specific diagnostics and structured edit reports. next=Use fileprobe before editing unknown config files. | Use jsonshape after JSON config changes. gitshape: Summarize Git status or diff shape into concise AI-friendly file, line, and touched-symbol reports. Better than: reading raw git status and diff noise when you first need compact status counters or changed-file summaries. Usage: gitshape [OPTIONS] [PATH] | gitshape [OPTIONS] status [PATH] | gitshape [OPTIONS] diff [REVISION_A] [REVISION_B] Example: gitshape . Guided: answer=Answer git status, branch, diff, and repository change shape. trust=Trust git command output and explicit revision/path filters. next=Use reposhape to connect git changes to ecosystems. | Use ctxpack or hitsnip for changed-file handoff. reposhape: Detect repository ecosystems, manifests, command entrypoints, and CI hints in one pass. Better than: manually browsing an unfamiliar repo when you first need the ecosystems, manifests, commands, and CI entrypoints. Usage: reposhape [OPTIONS] [PATH] Example: reposhape . Guided: answer=Answer repository ecosystems, manifests, entrypoints, and project layout. trust=Trust manifest detection under depth/hidden filters and parse diagnostics. next=Use codeshape for source declarations. | Use dotnetshape/sqlshape/gitshape for ecosystem-specific detail. dotnetshape: Inspect .csproj, Directory.Build.props/targets, Directory.Packages.props, project references, package versions, and .NET-specific project graph diagnostics. Better than: opening a .NET repo one file at a time when you first need project graph shape, shared MSBuild inheritance, package references, and build-shape warnings. Usage: dotnetshape [OPTIONS] [PATH] Example: dotnetshape . Guided: answer=Answer .NET project graph, inherited MSBuild properties, package references, and diagnostics. trust=Trust static XML parsing without invoking MSBuild; generated/effective values are labeled. next=Use asmref diagnose on built assemblies. | Use config to inspect Directory.Build or props files directly. unlock: Identify file lockers and perform unlock-aware file actions on Windows. Better than: ad-hoc PowerShell probing when a file is busy, locked, or refuses delete, move, rename, or copy. Usage: unlock [OPTIONS] who <PATH...> | unlock [OPTIONS] free <PATH...> | unlock [OPTIONS] move <PATH> <DEST> | unlock [OPTIONS] rename <PATH> <NEW_NAME> | unlock [OPTIONS] delete <PATH...> | unlock [OPTIONS] copy <PATH> <DEST> Example: unlock who .\target\debug\jsonlgrep.exe --json | ConvertFrom-Json | Select-Object -ExpandProperty results Guided: answer=Answer which processes lock files and perform unlock-aware copy/move/delete actions. trust=Trust restart-manager/handle-scan evidence and post-action filesystem checks. next=Use proctree on blocker PIDs. | Use recent after cleanup to confirm generated artifacts.