docs: `path` is directed by default but the top-level help never says so, and `diagnose multigraph` documents the opposite default for the same JSON flag

[bpinchukde-cpu]

Summary

graphify path is directed by default (deliberately, per #2487), but that default is not stated anywhere in the top-level help. graphify diagnose multigraph does document its own default, and documents it as the opposite behaviour — following the JSON directed flag. Reading the two side by side, a user reasonably concludes path should follow the flag too, and misreads a correct "no directed path" result as a bug.

This is a documentation issue only. The path behaviour itself is correct and I am not proposing to change it.

What the help says today

diagnose multigraph states its default explicitly:

    --directed              force directed post-build simulation
    --undirected            force undirected post-build simulation
                            (default follows JSON directed flag;
                             raw extraction with no flag defaults directed)

path lists neither flag, and states no default:

  path "A" "B"            shortest path between two nodes in graph.json
    --graph <path>          path to graph.json (default graphify-out/graph.json)

The flags exist and are discoverable only by triggering the usage error:

$ graphify path
Usage: graphify path "<source>" "<target>" [--graph path] [--directed|--undirected]

The actual resolution is in cli.py:

undirected = direction_flag == "undirected"

The JSON flag is never consulted — correct per #2487's reasoning, but nothing in the user-facing help conveys that, and the one place that mentions a JSON-flag-following default is a different subcommand.

Why it misleads (concrete case)

Tested on graphifyy 0.9.62, on a graph built through the Claude Code skill's default pipeline (build_from_json(..., directed=False)), 40,023 nodes / 98,736 edges.

$ graphify path "BacktestEngine" "market_data_1m_dir()"
No directed path found between 'BacktestEngine' and 'market_data_1m_dir()'. Re-run with --undirected to search ignoring edge direction.

$ head -c 40 graphify-out/graph.json
{
  "directed": false,

The file says "directed": false; path ran a directed search anyway. I concluded the command was ignoring the graph's own flag and was about to file that as a bug. It is not a bug — verified by measuring the file:

• 0 of 98,736 links carry _src/_tgt markers (this graph is post-Two extractor bugs systematically inflate god-node centrality (rationale fragments + calls direction inversion) #563, so direction rides in arc order)
• 48.8% of links have source <= target lexically, i.e. arc order is uncorrelated with sort order — not canonicalized, so the orientation is real
• sampled arcs are semantically correct, e.g. data_catalog_datacatalog_init -> core_paths_market_data_1m_dir [calls]

The "no directed path" answer was true: in that codebase the backtest engine receives a DataFrame and genuinely never reaches the path helper. But nothing available to the user at the command line distinguishes "true architectural answer" from "default was wrong for this graph" — and the top-level flag actively points the wrong way.

This is the consumer-facing half of #3495: that issue covers the export declaring directed: false while the links carry direction; this one is that the same mismatch surfaces in path's help, where the fix is cheap.

Suggested fix

Document path's default in the top-level help, in the same style diagnose multigraph already uses:

  path "A" "B"            shortest path between two nodes in graph.json
    --graph <path>          path to graph.json (default graphify-out/graph.json)
    --directed              force directed search
    --undirected            search ignoring edge direction
                            (default: directed — direction rides in link arc
                             order, not in the JSON `directed` flag, which
                             describes the storage container)

Optionally, add the same clarifying sentence to the "No directed path found" message, so a reader knows the directed default was intended rather than inherited from the file.

Environment

• graphifyy 0.9.62 (uv tool install), macOS 15.6 / Darwin 25.6.0, Python 3.13
• graph built via the Claude Code skill pipeline, default undirected build

Related

• path: shortest path runs on an undirected view, so results can traverse edges backwards #2487 — made path directed by default (the behaviour this asks to document)
• graphify extract exports graph.json with directed: false even though the link data carries subject→object direction; no CLI opt-in for a directed build #3495 — export declares directed: false while link data carries direction (the underlying mismatch)