{ "title": "Mercury Toolbox AI Prompt", "overview": [ "Mercury Toolbox is a set of small, focused Windows and PowerShell-friendly CLI tools for fast local inspection, transformation, and triage.", "The toolbox is optimized for AI-assisted terminal work: compact text by default, stable machine-readable output through `--json`, native model-readable TOON through `--toon`, and easy piping between commands.", "Prefer these tools when you need a narrow binary that explains a local situation quickly without opening a heavy UI or dumping unnecessary text." ], "selection_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." ], "tools": { "cjson": { "why": "pretty multi-line JSON when you need compact stable output and optional key sorting.", "use_when": "Compact JSON or JSONL before piping, diffing, or model input.", "guided_triage": { "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_actions": [ "Run jsonshape on the compacted payload when you need schema shape.", "Pipe to jq or toon for projection/model handoff." ] } }, "ison": { "why": "verbose JSON when a deterministic compact ISON representation is easier to scan or diff.", "use_when": "Convert between JSON and ISON records for compact structured handoff.", "prompt_example": "ison .\\fixtures\\json-family\\ison\\users.json", "guided_triage": { "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_actions": [ "Use isonl for line-oriented streams.", "Use toon when the next consumer is an AI model." ] } }, "isonl": { "why": "manual JSONL splitting when line-oriented ISON records are better for streaming or model input.", "use_when": "Convert between JSONL and ISONL line records.", "prompt_example": "isonl --from jsonl --to isonl .\\fixtures\\json-family\\ison\\users.isonl", "guided_triage": { "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_actions": [ "Pipe into jsonlgrep for filtering.", "Use cjson or toon for downstream compact handoff." ] } }, "zon": { "why": "hand-written compact table encodings when you need Zero Overhead Notation interop without Node tooling.", "use_when": "Convert JSON or JSONL to Zero Overhead Notation and back.", "prompt_example": "zon .\\fixtures\\json-family\\zon\\person.json", "guided_triage": { "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_actions": [ "Use jsonshape after decoding to validate shape.", "Use toon for model-facing structured summaries." ] } }, "tonl": { "why": "one-off scripts for compact JSON ETL, validation, query, indexing, or streaming filters.", "use_when": "Encode, decode, query, validate, index, stream-query, and ETL JSON-backed TONL data.", "prompt_example": "tonl query --where active=true .\\fixtures\\json-family\\tonl\\records.tonl", "guided_triage": { "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_actions": [ "Use jsonlgrep for simple JSONL filtering before TONL conversion.", "Use cjson or toon for compact handoff." ] } }, "jsonlgrep": { "why": "ad-hoc `jq` for simple field filters, projections, counts, and regex matches.", "use_when": "Filter JSONL logs, single-line JSON arrays, or structured event streams by field.", "prompt_example": "recent --root . --limit 20 --json | jsonlgrep 'path~=LogOutput' --pick modified_rfc3339,path --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer which JSONL records match field, regex, or projection filters.", "trust": "Trust parsed JSON records and explicit malformed-line diagnostics.", "next_actions": [ "Use jsonshape on matched records to inspect structure.", "Use toon or cjson for compact AI handoff." ] } }, "mhash": { "why": "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.", "use_when": "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.", "prompt_example": "mhash --algorithm sha256,blake3-256,xxh3-128 .\\dist\\MercuryToolbox.zip --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer file identity, checksum, manifest verification, or hash throughput questions.", "trust": "Trust algorithm labels, manifest verification status, and per-file error rows.", "next_actions": [ "Use fileprobe first when the file type is unknown.", "Use jsonlgrep or jq to filter manifest rows." ] } }, "jsonshape": { "why": "opening raw payloads when you first need the shape, key paths, or a schema diff.", "use_when": "Summarize JSON or JSONL into path/type stats, or diff two shape reports.", "guided_triage": { "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_actions": [ "Use jsonlgrep to isolate records before reshaping.", "Use cjson to normalize payloads before comparing." ] } }, "recent": { "why": "manual directory scans when you just need the freshest files and `.gitignore` awareness.", "use_when": "List recently changed files or directories.", "guided_triage": { "answer": "Answer which files or directories changed recently.", "trust": "Trust timestamp filters and gitignore-aware discovery within the selected root.", "next_actions": [ "Pipe paths into fileprobe or outline.", "Use hitsnip or ctxpack after narrowing files." ] } }, "pathshadow": { "why": "guessing PATH order when the wrong executable is being picked.", "use_when": "Show which executable wins and which ones are shadowed.", "prompt_example": "pathshadow python npm --shell powershell --summary --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer which executable wins on PATH and which candidates are shadowed.", "trust": "Trust resolved filesystem candidates and shell-aware summary rows.", "next_actions": [ "Use sysshape --group shell for broader environment context.", "Use argv quote when command invocation quoting is suspicious." ] } }, "portping": { "why": "jumping between multiple network tools for quick TCP and HTTP reachability checks.", "use_when": "Probe ports or health endpoints with timings.", "guided_triage": { "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_actions": [ "Use portunlock when a local port is unexpectedly occupied.", "Use await port/http to wait for readiness." ] } }, "portunlock": { "why": "guessing which process owns a port or hand-writing `netstat` and kill loops when a local listener refuses to go away.", "use_when": "Show and free local TCP or UDP port owners on Windows.", "guided_triage": { "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_actions": [ "Use proctree on the owning PID before freeing.", "Use portping after freeing or restarting a listener." ] } }, "msudo": { "why": "guessing whether Windows elevation relay support is available, or hand-writing `Start-Process -Verb RunAs` wrappers when you first need the current privilege status.", "use_when": "Top-level high-risk command: inspect Windows elevation relay status, token state, active session state, and host availability before any privileged launch.", "prompt_example": "msudo status --json | ConvertFrom-Json | Select-Object ok,host,supports_runas,is_elevated", "guided_triage": { "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_actions": [ "Start with msudo status --json.", "Use argv quote before privileged shell wrapping." ] } }, "asmtype": { "why": "manual reflection or ad-hoc PowerShell when you first need the type map from a managed assembly.", "use_when": "List managed assembly types and filter them by name, namespace, base type, interface, or matching members, with optional user-code-only screening.", "prompt_example": "asmtype .\\fixtures\\managed\\bin\\GameAssembly.dll --with-member-match 'Build|Launch' --show-matched-members --pick full_name,base_type,matched_members --json | ConvertFrom-Json", "guided_triage": { "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_actions": [ "Pipe JSONL into asmmember.", "Use asmflow find/xref when behavior matters." ] } }, "asmmember": { "why": "long reflection scripts when you need methods, fields, and properties from a known managed type.", "use_when": "Inspect managed type members with binding filters and compact signatures, including JSONL handoff from `asmtype` and user-code-only filtering.", "prompt_example": "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 --pick type_name,name,visibility,signature --json | ConvertFrom-Json", "guided_triage": { "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_actions": [ "Use asmflow body for IL details.", "Use asmapi diff when comparing versions." ] } }, "asmref": { "why": "guessing missing managed dependencies when you need a fast reference, resolution, or Unity/Rocket plugin closure diagnosis pass.", "use_when": "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.", "prompt_example": "asmref diagnose .\\fixtures\\managed\\bin\\GameAssembly.dll --resolve-dir .\\fixtures\\managed\\bin --format toon", "guided_triage": { "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_actions": [ "Run asmref diagnose for closure risks.", "Use asmapi diff on risky version changes." ] } }, "asmapi": { "why": "manual reflection diffs or brittle spreadsheet comparisons when you need to know what managed API changed between two DLL versions.", "use_when": "Compare two managed assemblies for added or removed public types, removed methods, signature changes, and MissingMethodException risks, with optional internal/all visibility.", "prompt_example": "asmapi diff .\\old\\0Harmony.dll .\\new\\0Harmony.dll --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer public API differences between managed assemblies.", "trust": "Trust metadata comparison under the chosen visibility scope.", "next_actions": [ "Use asmref diagnose to connect API drift to dependency closure.", "Use asmmember on removed or changed types." ] } }, "asmflow": { "why": "ad-hoc IL dump scripts or manual dnSpy browsing when you need callers, callees, field access, or string literals from a managed method quickly.", "use_when": "Inspect managed method bodies, IL summaries, and cross-references for Unity and general .NET reverse-engineering flows.", "prompt_example": "asmflow xref --assembly .\\fixtures\\managed\\bin\\GameAssembly.dll 'Game.UI.Windows.Windows.SpaceCraftConstructionWindow::StartProject' --json | ConvertFrom-Json", "guided_triage": { "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_actions": [ "Use asmtype/asmmember to find exact targets.", "Use ctxpack to hand off IL evidence." ] } }, "llvmobjdump": { "why": "raw llvm-objdump text when you need compact section, symbol, and disassembly shape for COFF/PE or object files.", "use_when": "Inspect object sections, symbol labels, and disassembly through LLVM backend discovery.", "prompt_usage": "llvmobjdump [OPTIONS] [PATH...]", "prompt_example": "llvmobjdump .\\target\\release-fast\\binmeta.exe --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer object sections, symbols, and disassembly shape through LLVM.", "trust": "Trust LLVM backend output plus parser warnings/raw blocks for unsupported regions.", "next_actions": [ "Use llvmreadobj for headers/imports/debug hints.", "Use pecalls or pesig for PE-focused call/function triage." ] } }, "llvmreadobj": { "why": "heavy binary viewers or raw llvm-readobj output when you need a bounded COFF/PE header, import/export, and debug/PDB summary.", "use_when": "Inspect COFF/PE headers, sections, imports, exports, and debug hints through LLVM backend discovery.", "prompt_usage": "llvmreadobj [OPTIONS] [PATH...]", "prompt_example": "llvmreadobj .\\target\\release-fast\\binmeta.exe --json | ConvertFrom-Json", "guided_triage": { "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_actions": [ "Use peimports/peexports for PE-focused grouping.", "Use llvmobjdump when code layout or disassembly is needed." ] } }, "llvmnm": { "why": "raw symbol-table dumps when you need stable symbol rows with kind, address, size, object/archive prefix, and source-line hints.", "use_when": "List and classify object symbols through LLVM nm output.", "prompt_usage": "llvmnm [OPTIONS] [PATH...]", "prompt_example": "llvmnm .\\target\\release-fast\\binmeta.exe --defined-only --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer defined/undefined symbols with stable LLVM nm rows.", "trust": "Trust POSIX-format symbol parsing and backend stderr tails.", "next_actions": [ "Use llvmobjdump for disassembly around symbols.", "Use llvmreadobj for object headers and debug hints." ] } }, "peexports": { "why": "manual PE export-table browsing when you want names, ordinals, RVA/VA, forwarders, and guided follow-up commands without opening a heavy PE debugger.", "use_when": "Inspect export surfaces, spot forwarded symbols, filter by name or ordinal, and use `report_quality`/`next_actions` to decide the next PE pass.", "prompt_usage": "peexports [OPTIONS] [PATH...]", "prompt_example": "peexports C:\\Windows\\System32\\kernel32.dll --forwarders-only --json | ConvertFrom-Json", "guided_triage": { "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_actions": [ "Use peimports to inspect dependencies.", "Use llvmreadobj --exports to cross-check LLVM output." ] } }, "peimports": { "why": "ad-hoc import-table triage when you need API families grouped into human-friendly categories with immediate callsite and role follow-ups.", "use_when": "Inspect imports by library, name, or category, quickly separate filesystem, registry, device I/O, NT, and network APIs, then follow emitted `next_actions`.", "prompt_usage": "peimports [OPTIONS] [PATH...]", "prompt_example": "peimports .\\target\\release-fast\\portping.exe --category device_io --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer imported APIs grouped by library and API category.", "trust": "Trust PE import table parsing plus report_quality evidence and limitations.", "next_actions": [ "Use pecalls on interesting categories.", "Use drvshape for driver-like/native profiles." ] } }, "pecalls": { "why": "guessing import callsites from raw disassembly when you want direct IAT matches plus trust metadata around best-effort disassembly parsing.", "use_when": "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.", "prompt_usage": "pecalls [OPTIONS] [PATH...]", "prompt_example": "pecalls .\\target\\release-fast\\portping.exe --api WSAStartup --json | ConvertFrom-Json", "guided_triage": { "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_actions": [ "Use peimports to choose categories.", "Use pesig to place callsites inside functions." ] } }, "pesig": { "why": "manual function-boundary and calling-convention inference when you need a quick v1 signal with explicit confidence and next-step context.", "use_when": "Infer function boundaries, source hints, and calling conventions from PE text and metadata, then pivot to imports, callsites, or raw objdump via `next_actions`.", "prompt_usage": "pesig [OPTIONS] [PATH...]", "prompt_example": "pesig .\\target\\release-fast\\portping.exe --min-confidence medium --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer likely PE function boundaries and calling-convention hints.", "trust": "Trust confidence/evidence per function and report_quality for parse completeness.", "next_actions": [ "Use pecalls to connect functions to APIs.", "Use llvmobjdump for raw disassembly context." ] } }, "pestrrefs": { "why": "opening a disassembler and a string viewer separately when you need string hits with direct xrefs and a clear next triage command.", "use_when": "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.", "prompt_usage": "pestrrefs [OPTIONS] [PATH...]", "prompt_example": "pestrrefs .\\target\\release-fast\\portping.exe --contains DeviceIoControl --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer strings and direct code references in PE files.", "trust": "Trust direct VA/range xrefs; unresolved counts are not guessed.", "next_actions": [ "Use peimports to connect strings to APIs.", "Use ioctlscan for device-control constants." ] } }, "drvshape": { "why": "guessing the driver role from imports and exports when you want a compact Windows driver profile with IOCTL/import/callsite follow-ups already suggested.", "use_when": "Summarize likely WDM, KMDF, NDIS, minifilter, or native driver traits, surface heuristic driver hints, and treat `report_quality` as the trust boundary.", "prompt_usage": "drvshape [OPTIONS] [PATH...]", "prompt_example": "drvshape C:\\Windows\\System32\\drivers\\ndis.sys --json | ConvertFrom-Json", "guided_triage": { "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_actions": [ "Use ioctlscan to decode CTL_CODE candidates.", "Use pecalls --category device_io for dispatch/callsite evidence." ] } }, "ioctlscan": { "why": "searching for Windows IOCTL constants by hand when you want decoded CTL_CODE fields, code locations, and suggested role/callsite/string follow-ups.", "use_when": "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.", "prompt_usage": "ioctlscan [OPTIONS] [PATH...]", "prompt_example": "ioctlscan C:\\Windows\\System32\\drivers\\ndis.sys --json | ConvertFrom-Json", "guided_triage": { "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_actions": [ "Use drvshape to confirm driver role.", "Use pestrrefs or pecalls for surrounding evidence." ] } }, "binmeta": { "why": "opening heavy PE tooling or shelling out to signature utilities when you first need binary identity, PE basics, version resources, and Windows signing status.", "use_when": "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.", "guided_triage": { "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_actions": [ "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": { "why": "blindly opening files when you need a fast read-worthiness, encoding, or newline check first.", "use_when": "Classify files as text, binary, generated, minified, test, vendor, and more, including encoding, BOM, and newline diagnostics.", "guided_triage": { "answer": "Answer whether a path is text, binary, generated, minified, vendor, or worth opening.", "trust": "Trust bounded sniffing, encoding, newline, and classification diagnostics.", "next_actions": [ "Use outline or chunkcat for readable text.", "Use binmeta or stringscan for binary files." ] } }, "outline": { "why": "scrolling whole files when you only need the structure.", "use_when": "List top-level code or config structure.", "guided_triage": { "answer": "Answer top-level structure of source or config files.", "trust": "Trust parser-supported outlines and explicit unsupported-file diagnostics.", "next_actions": [ "Use defsnip for exact definitions.", "Use refs or codeshape for broader symbol maps." ] } }, "codeshape": { "why": "plain `tree` output when you need internal declarations and signatures without dumping full source files.", "use_when": "Map a codebase into files plus AST-backed declarations and signatures from the shared `codeindex` engine.", "guided_triage": { "answer": "Answer repository file/declaration shape with AST-backed summaries.", "trust": "Trust codeindex parser results and skipped-file diagnostics.", "next_actions": [ "Use defsnip to extract definitions.", "Use refs to find use sites." ] } }, "refs": { "why": "falling back to raw `rg` when you need exact use-sites or caller summaries for a known symbol.", "use_when": "Find exact symbol references or caller definitions through the shared `codeindex` engine with text fallback.", "guided_triage": { "answer": "Answer symbol references or callers across source files.", "trust": "Trust codeindex hits and caller grouping under the selected roots.", "next_actions": [ "Use hitsnip to expand hit context.", "Use defsnip for definition bodies." ] } }, "snip": { "why": "dumping whole files when you only need exact lines, matches, or symbols.", "use_when": "Extract precise snippets from files or stdin.", "guided_triage": { "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_actions": [ "Use hitsnip after rg for multiple hits.", "Use ctxpack to bundle snippets." ] } }, "defsnip": { "why": "line-number snippets when you need the full function, class, or method body even after nearby edits move the lines.", "use_when": "Extract full AST-backed definitions by exact symbol name through the shared `codeindex` engine.", "guided_triage": { "answer": "Answer full AST-backed definition blocks for symbols.", "trust": "Trust codeindex definitions and language support; no match means broaden symbol/root.", "next_actions": [ "Use refs for callers/use sites.", "Use ctxpack to package the definition with nearby context." ] } }, "ctxpack": { "why": "hand-assembling ad-hoc prompt context from files, hits, diagnostics, and definitions.", "use_when": "Pack files, snippets, hits, diagnostics, or definition JSON into compact context blocks.", "guided_triage": { "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_actions": [ "Use fileprobe/codeshape before packing broad roots.", "Use diagpick or hitsnip to feed focused evidence." ] } }, "chunkcat": { "why": "huge file dumps when you need deterministic windows.", "use_when": "Read large text files in bounded chunks, including quick tail-style log windows.", "prompt_example": "chunkcat .\\BepInEx\\LogOutput.log --max-lines 20 --tail", "guided_triage": { "answer": "Answer a bounded chunk or inventory of a large text file.", "trust": "Trust chunk indices, line ranges, and binary detection.", "next_actions": [ "Use snip when you know the exact line range.", "Use hitsnip to expand search hits into chunks." ] } }, "hitsnip": { "why": "raw `rg` hit lists when you need merged readable context or the enclosing definition instead of a tiny window.", "use_when": "Turn search hits into compact snippets or promote them to enclosing definitions.", "prompt_example": "rg -nH \"helper\" .\\fixtures\\polyglot\\repo\\src\\lib.rs | hitsnip --def", "guided_triage": { "answer": "Answer merged snippets around rg-style search hits.", "trust": "Trust hit parsing and merge ranges; malformed hit lines are reported.", "next_actions": [ "Use rg -nH to feed hits.", "Use defsnip when the hit is inside a known symbol." ] } }, "diagpick": { "why": "reading full logs when you need the actionable errors first and want direct source or definition context.", "use_when": "Extract compiler or runtime diagnostics from noisy logs, with optional snippets and enclosing definitions.", "prompt_example": "diagpick .\\fixtures\\diag\\rust-errors.txt --def", "guided_triage": { "answer": "Answer actionable diagnostics extracted from compiler/build/log text.", "trust": "Trust recognized diagnostic formats and preserved source context.", "next_actions": [ "Use snip on referenced files/lines.", "Use runprobe to capture the failing command reproducibly." ] } }, "logshape": { "why": "reading repetitive logs line by line when you need the dominant patterns.", "use_when": "Group recurring log lines into templates.", "guided_triage": { "answer": "Answer repeated log templates, incidents, and message clusters.", "trust": "Trust grouping counts and examples; rare lines may stay as individual templates.", "next_actions": [ "Use diagpick for actionable errors.", "Use jsonlgrep when logs are structured JSONL." ] } }, "stringscan": { "why": "a full reverse-engineering pass when you first need identity clues from strings.", "use_when": "Extract and classify high-signal strings from binaries or blobs.", "guided_triage": { "answer": "Answer strings and classified hints from arbitrary blobs.", "trust": "Trust extracted string offsets and classification labels; encoding limits are explicit.", "next_actions": [ "Use binmeta first for binary identity.", "Use pestrrefs for PE strings with xrefs." ] } }, "toon": { "why": "verbose JSON when you want a denser structured text form.", "use_when": "Convert between JSON and TOON.", "guided_triage": { "answer": "Answer compact model-readable TOON from JSON/JSONL or decode TOON back.", "trust": "Trust parser/encoder diagnostics and document wrapper metadata.", "next_actions": [ "Use native --toon on Mercury producers when available.", "Use cjson/jsonshape before converting questionable JSON." ] } }, "csvshape": { "why": "opening huge CSV or TSV files when you first need the columns, rough types, blanks, example values, or a shape diff.", "use_when": "Summarize large CSV or TSV files into compact schema/bounded stats, or diff two CSV shapes.", "guided_triage": { "answer": "Answer CSV/TSV delimiter, columns, row counts, and schema differences.", "trust": "Trust parsed rows under the detected or requested delimiter.", "next_actions": [ "Use jsonshape after converting CSV to JSON externally.", "Use config or sqlshape when CSV describes configuration/data imports." ] } }, "sqliteshape": { "why": "dropping into an interactive SQLite shell when you only need schema, sample rows, light table stats, or a shape diff.", "use_when": "Inspect SQLite databases read-only with compact schema/table summaries, or diff two SQLite shapes.", "guided_triage": { "answer": "Answer SQLite tables, columns, indexes, triggers, and schema diffs.", "trust": "Trust SQLite catalog queries against the selected database file.", "next_actions": [ "Use sqlshape for normalized cross-engine reports.", "Use jsonshape/csvshape on exported data samples." ] } }, "sqlshape": { "why": "hand-writing per-engine catalog queries or exposing raw connection strings when you need a normalized cross-database schema report or diff.", "use_when": "Inspect PostgreSQL, MySQL/MariaDB, SQLite, SQL Server, or DuckDB schemas read-only with redacted connection sources and normalized cross-engine diffs.", "prompt_example": "sqlshape --engine sqlite --url .\\fixtures\\sqliteshape\\sample.db --json | ConvertFrom-Json", "guided_triage": { "answer": "Answer normalized SQL schema across SQLite, PostgreSQL, MySQL/MariaDB, SQL Server, or DuckDB.", "trust": "Trust engine-specific introspection and redacted connection reporting.", "next_actions": [ "Use sqliteshape for SQLite-specific detail.", "Use config to inspect connection/config files safely." ] } }, "unityasset": { "why": "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.", "use_when": "Inspect Unity serialized assets, bundles, and YAML objects, then trace refs, dump fields, or extract payloads such as TextAsset, MonoScript, AudioClip, and VideoClip.", "guided_triage": { "answer": "Answer Unity asset indexes, object dumps, references, and extraction writes.", "trust": "Trust parsed serialized files/bundles and explicit unresolved reference rows.", "next_actions": [ "Use unitydiag for runtime/log symptoms.", "Use asmtype/asmflow for managed script assemblies." ] } }, "unityprobe": { "why": "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.", "use_when": "Install and query a read-only BepInEx bridge for live scenes, objects, and static state in a running Mono Unity game on Windows.", "guided_triage": { "answer": "Answer read-only Unity runtime bridge status, object search, and inspection.", "trust": "Trust explicit bridge install/status and Windows named-pipe reachability.", "next_actions": [ "Use unitydiag when runtime logs explain bridge issues.", "Use unityasset for offline assets." ] } }, "unitydiag": { "why": "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.", "use_when": "Summarize Unity Player.log and BepInEx logs into grouped incidents, normalized messages, and domain-aware failure summaries.", "guided_triage": { "answer": "Answer Unity/BepInEx log incidents, grouped frames, and mod/runtime warnings.", "trust": "Trust discovered log paths, grouping counts, and preserved stack snippets.", "next_actions": [ "Use asmref diagnose for plugin dependency issues.", "Use unityprobe when live object state is needed." ] } }, "envdiff": { "why": "hand-comparing environment variables before and after a script, especially around PATH pollution and batch wrappers.", "use_when": "Snapshot, diff, or run commands while reporting environment-variable changes.", "prompt_usage": "envdiff [OPTIONS] run --shell cmd|pwsh|raw -- ", "prompt_example": "envdiff run --shell cmd -- .\\scripts\\set-env.cmd", "guided_triage": { "answer": "Answer environment variable changes before/after a command or between snapshots.", "trust": "Trust captured before/after maps and PATH segment deltas.", "next_actions": [ "Use pathshadow after PATH changes.", "Use sysshape for broader shell/tool inventory." ] } }, "proctree": { "why": "flat process lists when you need parent-child context, short command lines, and lingering orphan hints.", "use_when": "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.", "prompt_usage": "proctree [OPTIONS] system|root |run -- ", "prompt_example": "proctree system --match 'pwsh|Mercury' --include-cmdline", "guided_triage": { "answer": "Answer process trees, rooted processes, and command ancestry.", "trust": "Trust OS process snapshots at capture time; short-lived processes may disappear.", "next_actions": [ "Use portunlock for port owners.", "Use runprobe to capture command execution shape." ] } }, "sysshape": { "why": "asking users ad-hoc setup questions or checking versions one tool at a time when you need a compact local machine inventory first.", "use_when": "Capture a compact local system and tool inventory for AI-friendly triage, including shell hints, path-like duplication, and probe status.", "prompt_example": "sysshape --json --env safe --group shell | ConvertFrom-Json", "guided_triage": { "answer": "Answer machine, shell, environment, and tool inventory shape.", "trust": "Trust detected command paths/versions and grouped environment metadata.", "next_actions": [ "Use pathshadow for a specific executable winner.", "Use envdiff around commands that mutate the environment." ] } }, "runprobe": { "why": "reading fragile shell text when what you really need is the stable result object for one command run.", "use_when": "Run one command and capture exit code, duration, timeout status, and bounded output tails.", "guided_triage": { "answer": "Answer command exit code, duration, stdout/stderr tails, and timeout behavior.", "trust": "Trust captured process result and bounded output tails.", "next_actions": [ "Use diagpick on captured stderr/stdout.", "Use envdiff run when environment mutation matters." ] } }, "await": { "why": "writing ad-hoc polling loops for files, ports, HTTP endpoints, or repeat-until-success commands.", "use_when": "Wait for a path, TCP target, HTTP endpoint, or command condition with bounded polling.", "guided_triage": { "answer": "Answer whether a path, port, HTTP endpoint, or command became ready before timeout.", "trust": "Trust polling attempts, final state, and timeout status.", "next_actions": [ "Use portping for one-shot endpoint detail.", "Use runprobe for command readiness probes." ] } }, "argv": { "why": "guessing how PowerShell or cmd really passed arguments to a native process.", "use_when": "Quote argv for `pwsh` or `cmd`, or inspect what a shell actually passed to a native process.", "guided_triage": { "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_actions": [ "Use runprobe to execute the quoted command.", "Use msudo status before privileged shell wrapping." ] } }, "config": { "why": "fighting `jq` or hand-editing config files when you need safe slash-pointer reads or edits across common formats.", "use_when": "Read, inspect, list, set, or delete config values in JSON, YAML, TOML, env, and INI files.", "prompt_usage": "config [OPTIONS] [PATH] | config [OPTIONS] [POINTER] [VALUE]", "prompt_example": "config get .\\package.json /version", "guided_triage": { "answer": "Answer get/set/delete operations over JSON/YAML/TOML/env/INI config paths.", "trust": "Trust parser-specific diagnostics and structured edit reports.", "next_actions": [ "Use fileprobe before editing unknown config files.", "Use jsonshape after JSON config changes." ] } }, "gitshape": { "why": "reading raw `git status` and diff noise when you first need compact status counters or changed-file summaries.", "use_when": "Summarize Git status or diff shape into concise AI-friendly file, line, and touched-symbol reports.", "guided_triage": { "answer": "Answer git status, branch, diff, and repository change shape.", "trust": "Trust git command output and explicit revision/path filters.", "next_actions": [ "Use reposhape to connect git changes to ecosystems.", "Use ctxpack or hitsnip for changed-file handoff." ] } }, "reposhape": { "why": "manually browsing an unfamiliar repo when you first need the ecosystems, manifests, commands, and CI entrypoints.", "use_when": "Detect repository ecosystems, manifests, command entrypoints, and CI hints in one pass.", "guided_triage": { "answer": "Answer repository ecosystems, manifests, entrypoints, and project layout.", "trust": "Trust manifest detection under depth/hidden filters and parse diagnostics.", "next_actions": [ "Use codeshape for source declarations.", "Use dotnetshape/sqlshape/gitshape for ecosystem-specific detail." ] } }, "dotnetshape": { "why": "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.", "use_when": "Inspect .csproj, Directory.Build.props/targets, Directory.Packages.props, project references, package versions, and .NET-specific project graph diagnostics.", "guided_triage": { "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_actions": [ "Use asmref diagnose on built assemblies.", "Use config to inspect Directory.Build or props files directly." ] } }, "unlock": { "why": "ad-hoc PowerShell probing when a file is busy, locked, or refuses delete, move, rename, or copy.", "use_when": "Identify file lockers and perform unlock-aware file actions on Windows.", "guided_triage": { "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_actions": [ "Use proctree on blocker PIDs.", "Use recent after cleanup to confirm generated artifacts." ] } } } }