Improve discoverability of board-specific flash workflows for AI agents

[jtligon]

Summary

When using jumpstarter via MCP or CLI (jmp shell -- j ...) from an AI coding agent, there's no programmatic way to discover the correct flash workflow for a given board type. The agent has to guess, and guessing wrong results in silent hangs rather than actionable errors.

What happened

@jtligon prompted an AI coding agent (Claude Code) with:

"Build this demo for 8775 and flash that build to a board. If it fails, show me the relevant errors in the serial console log."

The agent:

1. Successfully built an aarch64 disk image for the ride4_sa8775p_sx_r3 target
2. Leased a board-type=qc8775 board via jmp create lease
3. Attempted to flash the raw disk image:

j storage flash /path/to/image.aarch64.img

This hung indefinitely — the RIDE SX boards require per-partition flashing via fastboot:

j storage flash -t system_a:system_a.img -t boot_a:boot_a.img

The agent had no way to discover this from j storage flash --help, the exporter metadata, or the MCP tool schema. A human had to intervene with board-specific knowledge.

The discoverability gap

• j storage flash --help shows generic examples but doesn't indicate which approach applies to the currently connected board
• Exporter/board metadata (board-type=qc8775) doesn't expose flash requirements (partition targets, image format, flash method)
• The MCP server doesn't surface board-specific workflows or constraints
• There's no j storage info or similar introspection command that reports what the connected board needs

Suggestions (not mutually exclusive)

1. Board-aware flash help — j storage flash --help or a new j storage info command could report the connected board's flash requirements: required partition targets, supported image formats, whether raw full-disk images are accepted vs. per-partition images required.

2. Exporter metadata — include flash-relevant info in the exporter's advertised capabilities or labels (e.g., flash-method=fastboot, flash-partitions=boot_a,system_a,system_b), queryable via jmp get exporters or MCP tools. This lets agents plan the workflow before leasing.

3. MCP tool descriptions — the MCP storage_flash tool schema could include board-specific parameter guidance when connected to a leased device, so agents know which -t targets are required.

4. Validation / early failure — if a board requires partition targets and none are provided, j storage flash should fail fast with a helpful error message listing the required partitions, rather than hanging silently. This is probably the highest-impact change regardless of agent usage.

Context

This came up during a real agentic workflow: building an automotive OS image and attempting to flash it to hardware via jumpstarter. The MCP integration exists specifically for agent use, so this discoverability gap directly undermines the agent experience. The agent successfully navigated leasing, building, and invoking the flash command — but couldn't discover the correct invocation without human knowledge of the board's fastboot partition scheme.

🤖 Generated with Claude Code

[bennyz]

 j storage flash --help
Usage: j storage flash [OPTIONS] [PATH]

  Flash image to device.

  Examples:
    # OCI auto-detection
    j storage flash oci://registry.com/image:tag

    # OCI with explicit partition->filename mapping   j storage flash -t
    boot_a:boot.img oci://registry.com/image:tag

    # OCI with registry credentials (via env vars)   OCI_USERNAME=user
    OCI_PASSWORD=pass j storage flash oci://registry.com/image:tag

    # Single file to partition   j storage flash /local/boot.img --target
    boot_a

    # Multiple files   j storage flash -t boot_a:/local/boot.img -t
    system_a:/local/system.img

    # HTTP URLs   j storage flash -t boot_a:https://example.com/boot.img

  Environment variables:
    OCI_USERNAME  Registry username for private OCI images
    OCI_PASSWORD  Registry password for private OCI images

Options:
  -t, --target TEXT             Target spec as partition:path for multi-
                                partition or just partition for single file
  --power-off / --no-power-off  Power off device after flashing (default)
  --help                        Show this message and exit.

help does show it though