Crockan/MercuryToolbox
1
0
Fork 1
Code Issues Pull Requests Releases 1 Wiki Activity

chore(release): prepare public source release

Browse Source
This commit is contained in:
MercuryToolbox Release
2026-07-18 15:41:59 +08:00
commit e365e5df4d
508 changed files with 163373 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/ai/mercury-toolbox-ai-prompt.md
+62
View File
@@ -0,0 +1,62 @@
# 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.