# Toolbox V1.5 Design

## Goal

Promote the existing four commands from "usable prototypes" to daily-driver tools by pairing feature upgrades with first-class help and documentation, and add a production-grade `binmeta` command for fast binary triage in AI-heavy terminal workflows.

## Scope

- Upgrade `jsonlgrep` with nested field paths and negative field predicates.
- Upgrade `recent` with regex-based name filtering.
- Upgrade `pathshadow` with clearer shadowing explanations in text and JSON output.
- Upgrade `portping` with selectable HTTP method and expected status checks.
- Add concrete examples to `--help` output for all commands.
- Update `README.md` with scenario-driven examples and PowerShell pipeline usage.
- Add `binmeta` as a new CLI command for binary metadata inspection on Windows PE files, with graceful handling for non-PE files.

## Non-Goals

- No GUI or TUI work.
- No installer, release automation, or Scoop packaging in this iteration.
- No multi-format binary analysis beyond production-grade PE support plus safe fallback summaries for unknown formats.

## Command Changes

### `jsonlgrep`

- Extend query syntax to support `field!=value` and `field!~=regex`.
- Resolve dotted field paths such as `event.user.name`.
- Treat scalar JSON values consistently so exact matches and text projections also work for numbers, booleans, and null.
- Improve `--help` with copy-pasteable file and pipeline examples.

### `recent`

- Add `--name <REGEX>` to filter by file or directory basename.
- Preserve `.gitignore`-aware traversal and current sorting behavior.
- Improve `--help` with examples for recent Rust work, recent directories, and JSON pipeline usage.

### `pathshadow`

- Append stable explanation fields to JSON output so scripts and AI can tell why an entry won or lost.
- Include PATH rank and winner path context where applicable.
- Keep text output compact but clearer about origin and shadowing reason.
- Improve `--help` with explicit PATH diagnosis examples.

### `portping`

- Add `--method GET|HEAD` for HTTP(S) requests.
- Add `--expect-status` to turn mismatched HTTP status codes into probe failure while keeping actual status visible.
- Preserve TCP behavior unchanged.
- Improve `--help` with health-check and HEAD examples.

### `binmeta`

- Input: one or more file paths from argv or stdin lines.
- Text output: one concise summary line per file for human scanning.
- JSON output: one object per file with stable fields for automation and AI use.
- PE analysis:
  - file kind, machine/architecture, subsystem, executable vs DLL hint, PE timestamp
  - section summaries
  - imported DLLs and imported symbol count summary
  - exported symbol count summary when available
  - SHA-256, file size, modified time
  - heuristic hints for `.NET`, Unity, IL2CPP, Mono, and BepInEx-related artifacts
- Non-PE fallback:
  - still emit hash, size, modified time, file extension, and "not_pe" kind without failing the whole command

## Testing Strategy

- Add focused unit tests for new parsing helpers and negative query logic.
- Expand integration tests to cover help examples and new CLI flags.
- Add `binmeta` integration tests against:
  - a known text fixture for non-PE fallback
  - compiled workspace binaries for PE parsing
- Keep the existing Jade verification gate unchanged.

## Risks

- PE parsing APIs can be noisy; the implementation should wrap parser details behind small helpers.
- `binmeta` hints must remain heuristic and clearly labeled as hints, not definitive claims.
- Help text examples must stay in sync with actual behavior, so tests should assert representative help fragments.