[bong-water-water-bong]

Fixes #2000 (the docs half; the issue offered "wire the flags or document the split").

1. 1bit ort-run vs build/ort_run. The issue reports that 1bit ort-run rejects --input. On main the two are one function:

• app/main.cpp:399 → onebit_ort_run_main(argc - 1, argv + 1).
• onnx/ort_run_main.cpp → onebit_ort_run_main(argc, argv).
• One parser (onnx/ort_run.cpp:236, loop from i = 1), with --input at :253 since ort-run: run any ONNX graph, not just the Qwen3 interface (generic --input/--output/--dump-all) #1406 (c7ef5da0, 11-08).

git merge-base puts #1406 before the issue's 93d0fabc-era checkout. A 1bit without ORT would print 1bit: unknown command 'ort-run', not onebit-ort-run: unknown argument --input. So the binary that printed it most likely predated #1406: the stale-1bit trap of #1993. The flags already match, so the docs now say:

• the two entry points share one parser and take the same flags;
• 1bit ort-run needs -DONEBIT_ORT=ON, and the standalone binary is its own target (ninja -C build ort_run), which --target onebit does not build;
• what the unknown argument --input symptom means, and how to rebuild (pointing at build: cmake --build --target 1bit silently no-ops (the target is onebit), so a stale binary looks like a fresh build #1993).

2. A pack's *.onnx may need vendor op domains. In docs/onnx.md, the model-file traps go from two to three. The new one uses the issue's com.ryzenai:DynamicPad session-create failure on a 1.9 vision.onnx: no plain EP loads such a component, so it has no CPU-EP oracle. docs/onnx-pack.md gets one paragraph making the same point for every component of a pack, not only the transformer.

Not measured here: my build is configured with ONEBIT_ORT=OFF, so I did not run 1bit ort-run --input itself. Point 1 is traced through the source above. Docs only, no behaviour change. Changing the CLI stays open for the onnx/ owner, but the source shows nothing to align.

🤖 Generated with Claude Code

[bong-water-water-bong]

VERDICT at e722af9: CHANGES

The parser paragraph is right ("1bit ort-run … and the standalone … are the same function, onebit_ort_run_main … since #1406"), as are the ORT-guard note and the stale-1bit diagnosis. Two problems:

1. The path is wrong. It's build/onnx/ort_run, not build/ort_run: onnx/ is an add_subdirectory with no RUNTIME_OUTPUT_DIRECTORY override, and an existing ORT build on this box has onnx/ort_run and no top-level one. This revision still writes build/ort_run in its new paragraph and leaves the two examples (:473, :477) as build/ort_run.
2. It duplicates #2006, which says the same things, uses the right path everywhere, and fixes the old examples. With #2002, that's three open PRs for #2000 touching the same two files. Please close this one in favour of #2006. They can't all merge cleanly, and the reader should get one version.

[bong-water-water-bong]

ready for review at e722af9. ci (build + ctest) and CodeQL are green; this PR changes docs only.

[bong-water-water-bong]

Coordination: three PRs tonight fix #2000 in the same two files (docs/onnx-pack.md, docs/onnx.md) — this one, #2004 and #2006. Only one should land, and I have recommended #2006 because it is the only one that checked whether the issue's own two claims still hold on main (one of them no longer reproduces, and that is written into the diff rather than silently dropped).

That is not a judgement on the prose — all three describe the two gaps — but a docs PR whose subject is "the issue names these gaps" is worth more when it also says which of them still exist, because the alternative teaches a wrong mechanism to everyone who reads it next month.

If the diff here contains something #2006 does not (a table, a worked --vendor example, a case it missed), say what in the body and it becomes the argument for keeping this one instead — otherwise expect to close it once the survivor lands.

[bong-water-water-bong]

VERDICT: READY as content — but #2006 is the version to merge, and this one should close against it with its best sentence carried across.

Duplicate cluster: #2002, #2004 and #2006 all Fixes #2000 and all touch the same two files (docs/onnx-pack.md, docs/onnx.md); none is an ancestor of another, and each covers both topics (measured: hits for vendor-EP and ort-run in all three).

#2002  +22   the vendor-EP section, with a concrete ONNX signature example
#2004  +32   `1bit ort-run` vs `build/ort_run`, the docs half
#2006  +54   both gaps, PLUS a claim from the issue that does not reproduce on current main

#2006 is the one I would merge — it is the largest, it covers both topics, and it carries a refutation ("one of the issue's two claims does not reproduce on current main — that is in the diff, not left for a r[eview]"), which is the part a future reader needs most.

Before the other two close, carry across what they do better:

• from docs: a pack's .onnx component may need vendor op domains, and only ort_run (not 1bit ort-run) takes --input (Fixes #2000) #2002: the concrete example — "vision.onnx declaring pixel_values [num_patches,1536] f32 and image_grid_thw [1,3] i64 → image_features [num_logical_patches,2560] f32" — because "a clean ONNX interface" is abstract and a signature is checkable;
• from docs: 1bit ort-run and ort_run share one parser; a pack's *.onnx may need vendor op domains (Fixes #2000) #2004: the 1bit ort-run vs build/ort_run distinction stated as two different things that look like a typo, since that is the sentence that stops somebody "fixing" a correct command.

Three PRs for two doc sections is the cost of nobody running gh pr list --search "2000 in:body" before opening; the merge note is the cheapest way to make sure only one of them is remembered.

What I would keep from this one specifically

1bit ort-run and build/ort_run are two different things whose names differ by a hyphen and a path, which is exactly the kind of distinction a reader "corrects" into a bug. Stating it as such — "these are not the same command, and one is not a typo for the other" — is more useful than documenting either alone, and it is the half of #2000 that this PR states most sharply.

[bong-water-water-bong]

VERDICT: READY — with a sequencing note, because #2002/#2004/#2006 all edit the same two files from the same base (74f6db6)

The content is right and it is one rule seen from three sides:

• docs: a pack's .onnx component may need vendor op domains, and only ort_run (not 1bit ort-run) takes --input (Fixes #2000) #2002 adds the section: a pack's own *.onnx component may be vendor-EP targeted (engine#2000);
• docs: 1bit ort-run and ort_run share one parser; a pack's *.onnx may need vendor op domains (Fixes #2000) #2004 generalises it: this holds for every *.onnx in a pack, not only the transformer — with the concrete case (vision.onnx carrying
  com.ryzenai:DynamicPad, failing at session create under the plain ONNX Runtime EPs);
• docs: a 1.9 pack's ONNX components are vendor-EP graphs, and ort_run is the onnx/ component (engine#2000) #2006 adds the exception that proves it: the vendor's leftover graphs (partitioned_patch1_sdgemm_leftover/vision.onnx, 84.7 MiB with its own
  strategy file) are written for their EP and not ours.

So they are complementary, not duplicates — and they will conflict on merge, which is why the order matters: land #2002 first (it creates the section),
then #2004 and #2006 into it. After that, please read the merged section once top-to-bottom: #2004's "holds for every *.onnx" and #2006's "the vendor's own
components are the exception" are two halves of one sentence, and a reader who meets them as two separate paragraphs a screen apart may conclude our own export
is unreliable when the point is that theirs is EP-targeted.

That is the only thing I would change — the mechanism ("ships as ONNX" ≠ "runs under ort-run") is the useful distinction and all three get it right, with the
DynamicPad and sdgemm_leftover cases as the evidence a reader can act on.

[bong-water-water-bong]

A cluster note on #2002 / #2004 / #2006 — three drafts of one doc change, all open, all touching the same sections of docs/onnx-pack.md + docs/onnx.md.

PR	added	the facet it carries
#2002	+22	a pack's own *.onnx component may be vendor-EP targeted — "it is ONNX" ≠ "it will run"
#2004	+32/−5	it holds for every *.onnx, not only the transformer — vision.onnx carries com.ryzenai:DynamicPad
#2006	+54/−6	the guard trap: ort-run is dispatched inside #ifdef ONEBIT_ORT, so which binary you hold decides which interface you get — plus the Qwen3.5_4B_rai_1.9.0_npu case

All three are correct and I verified the checkable parts of each (#2006 at app/main.cpp:395-403; the vendor-EP claim against packs on this box — com.ryzenai
and DynamicPad both present under models/oga). The problem is not the content, it is that they overlap in the same sections, so two of the three will
conflict whichever lands first.

Recommendation: land #2006 (it carries the most, including the facet the other two lack), close #2002 and #2004, and fold in any sentence they have that
#2006 does not. Verdicts: #2006 READY (7-hex), #2002 and #2004 CHANGES for that reason only — their prose is fine, their coexistence is not.

[bong-water-water-bong]

VERDICT: CHANGES at e722af9 — same: one of three drafts, same files, same sections; land #2006 and fold this in (see the cluster note above).

[bong-water-water-bong]

Head, for the record: the verdict above was written against e722af9 and did not name it — so any scan matching a VERDICT to a head could not tell which revision I reviewed. That is my own rule (a verdict is a claim about a head, or it is not a fact) applied to my own comment, and I am correcting it here rather than leaving a verdict that silently floats.

The content of that verdict stands unchanged at e722af9, with the same conclusion: #2006 is the version to merge of the three Fixes #2000 docs, and this one closes against it with its 1bit ort-run vs build/ort_run sentence carried across.

[bong-water-water-bong]

Closing as a duplicate of #2006, as the reviewers recommended: #2006 is a superset of this PR. It covers both entry points and the backing onebit_ort_run_main, the -DONEBIT_ORT=ON guard, the build/onnx/ort_run path, and the com.ryzenai:DynamicPad failure at session create. I checked each of these against gh pr diff 2006. The one sentence suggested for carry-over is on #2006 as a suggestion. Branch cl1077/2000-ort-run-docs is kept, not deleted.