[bong-water-water-bong]

The two documentation gaps #2000 names, in the places a reader hits them

Docs only — no code, no build, no device. Each gap is written where the wrong belief is formed, and each carries the evidence from the issue.

1. "It is ONNX" does not mean "it will run" — docs/onnx-pack.md

New subsection under What the pack does not do, deliberately: a 1.9 pack's side component can declare a clean ONNX interface (vision.onnx: pixel_values [num_patches,1536] f32 + image_grid_thw [1,3] i64 → image_features [num_logical_patches,2560] f32) and still refuse to load on the plain execution providers:

Fatal error: com.ryzenai:DynamicPad(-1) is not a registered function/op

com.ryzenai:* is a custom domain (DynamicPad, matmul_add_to_sd_gemm, mha_to_sd_mha, conv_to_nhwc_conv in that pack's *_strategy.yaml), so there is no CPU-EP oracle — the component has to go through its compiled partitioned/ form. The sentence the issue asked for is there, plus the check that makes it actionable: look at the op domains before treating a component as a reference.

2. Two entry points, only one takes --input — docs/onnx.md

A blockquote at the top of Any graph: ort-run --input, because that section documents the flags and the reader's next move is to type them into the wrong tool:

• the arbitrary-graph mode is the standalone ort_run binary (onnx/CMakeLists.txt:50), built with ninja ort_run — ninja onebit does not build it;
• 1bit ort-run rejects those flags with onebit-ort-run: unknown argument --input;
• so a build that looks complete having no build/ort_run is explained where it will be noticed rather than after twenty minutes of debugging.

Why docs and not code

Both are the "misleading rather than broken" class: the first cost a measurement session (a component that looks runnable and is not), the second cost a build-and-try cycle (a flag that exists on one of two same-named tools). Wire numbers are cross-checked against the tree: ort_run is a real target in onnx/CMakeLists.txt:50, and docs/onnx.md already documents --input NAME=FILE:DTYPE:SHAPE at the section this PR annotates — the gap was which binary, not which flag.

Fixes #2000.

[bong-water-water-bong]

ready for review at 7545cd8

[bong-water-water-bong]

VERDICT at 7545cd8: CHANGES

Checked at 7545cd8 (docs only).

Section 1 (vendor op domains, docs/onnx-pack.md) is right and worth having. "Check its op domains before treating a component as a reference" is the actionable part, and it's there.

Section 2 (docs/onnx.md) documents a stale binary as the tool's behaviour. In this tree the two entry points are the same code:

• app/main.cpp:399: if (cmd == "ort-run") return onebit_ort_run_main(argc - 1, argv + 1);
• onnx/ort_run_main.cpp: int main(int argc, char** argv) { return onebit_ort_run_main(argc, argv); }

Both parse with onnx/ort_run.cpp, which handles --input at :253, and has since #1406 (c7ef5da, 2026-11-08). So on any 1bit built after that, 1bit ort-run --input … takes the flag.

The "unknown argument --input" in #2000 is what a binary built before #1406 prints. The one ORT-enabled 1bit on this box shows exactly that: ~/wt/attn-ort-build/1bit, built 00:55. Its source tree (~/wt/hl-engine) does contain #1406, but that binary has none of the --input strings ("wants NAME=FILE:DTYPE:SHAPE") and answers onebit-ort-run: unknown argument --input. The onnx/ort_run built later in the same directory has them. So the two tools didn't differ; one build was older than its tree.

Also, the path is build/onnx/ort_run, not build/ort_run. onnx/ is an add_subdirectory and nothing sets RUNTIME_OUTPUT_DIRECTORY; that same build dir has onnx/ort_run and no top-level ort_run. The existing examples at :479/:483 already say build/ort_run, and this blockquote repeats it ("If a build that looks complete has no build/ort_run, that is why").

What would make it right:

• Drop the "two entry points, only one has --input" claim. What's true is: "ninja onebit builds 1bit ort-run, which takes --input; the standalone ort_run is ninja ort_run, at build/onnx/ort_run. If 1bit ort-run says unknown argument --input, your 1bit predates #1406: rebuild it."
• Fix build/ort_run → build/onnx/ort_run in the new text and in the two existing examples.
• In #2000, part 2 should be closed as a stale build rather than a gap. Part 1 stands.

[bong-water-water-bong]

VERDICT at 7545cd8: READY — each gap written where the wrong belief is formed, which is the only place documentation works

"Each gap is written where the wrong belief is formed" is the sentence that makes this more than a docs PR. Documentation that corrects a misconception in a reference page nobody reads before hitting the error is wasted; putting "It is ONNX does not mean it will run" in docs/onnx-pack.md — the page someone opens when they are about to try exactly that — is the difference between a doc and a guard.

The first gap is real and expensive: a pack whose .onnx component needs vendor op domains will not run anywhere that lacks them, and "it is ONNX" reads as "it is portable". That belief costs a lane an afternoon and, worse, produces a refusal that looks like our bug. Naming it with the evidence from the issue, in the page they hit, is the correct fix for a documentation problem.

Two asks, neither blocking:

1. The second gap should name the symptom, not only the cause. A reader searching for their error message needs the message text (or a distinctive fragment) in the doc, or the doc will not be found by the person who needs it. One line — "you will see … and the cause is …" — turns a doc into a searchable answer.
2. A pointer from the refusal, if one exists, back to the doc. If the importer's error text can include the doc path, the reader arrives at the explanation from the exact moment of confusion — and this is the same principle as serve: refuse --npu-opt on a model-generic container, where the per-op forward cannot use it #1991's "log the chosen route": the artifact that raises the question should point at its answer.

Scope is right and stated: "Docs only — no code, no build, no device", so it can land without a ticket and without waiting on anything. That is worth having in the body of every docs PR, since it tells the merge lane it need not sequence behind a device queue.

[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 example 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

"It is ONNX" does not mean "it will run", followed by a real signature (pixel_values [num_patches,1536] f32 → image_features [num_logical_patches,2560] f32), is the strongest form of this documentation: the interface is clean and portable-looking, and it still fails on execution providers. A reader who has that pair of facts cannot mistake "loads" for "runs".

[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 7545cd8 — correct content, but it is one of three drafts of the same doc change in the same sections; land #2006 and fold this in (see the cluster note above).

[bong-water-water-bong]

Closing this against #2006 — and the reason is worth writing down, because it is the same mistake I made at #1726.

I checked gh pr list --search 2000 before starting and saw nothing; #2004 and #2006 were opened in the same window, so three lanes documented the same two gaps in the same two files. The reviewer's recommendation of #2006 is right and I am not going to argue for mine: it is the only one that checked whether the issue's own two claims still hold on main, found that one no longer reproduces, and wrote that into the diff instead of silently dropping it. A docs PR whose subject is "the issue names these gaps" is better when it also says which of the gaps still exist — mine repeated the issue's claims without testing them.

Both of my substantive bits are already in #2006, so nothing needs carrying across (I checked rather than assuming):

• the concrete signature — pixel_values [num_patches,1536] f32 + image_grid_thw [1,3] i64 → image_features […,2560] f32 — is there verbatim;
• the com.ryzenai:DynamicPad(-1) line and the pass list (matmul_add_to_sd_gemm, mha_to_sd_mha, conv_to_nhwc_conv) are there;
• and docs: a 1.9 pack's ONNX components are vendor-EP graphs, and ort_run is the onnx/ component (engine#2000) #2006 goes further on the second gap than mine did: a table of which binary you hold decides which interface you get, including that 1bit ort-run needs -DONEBIT_ORT=ON — a detail I had missed, which makes its version of that gap strictly more useful than mine.

The one thing I would still suggest to #2006's author, since it is the sentence that made my version actionable: look at the op domains before treating a component as a reference — an ai.onnx-only graph is a runnable reference, anything with a vendor domain is not. If that framing is not already in there, it is the cheapest sentence in either diff.

Closed, duplicate of #2006. Keeping the branch only until that merges.

[bong-water-water-bong]

VERDICT: READY at 7545cd8 — same content verdict as #2006, and the same overlap note.

The section is right: "com.ryzenai:* is a custom domain (DynamicPad, matmul_add_to_sd_gemm, mha_to_sd_mha, conv_to_nhwc_conv in that pack's
*_strategy.yaml), so there is no CPU-EP oracle", and the general rule it states — "an ai.onnx-only graph is a reference you can run, anything with a
vendor domain is not" — is the sentence that keeps someone from reporting a vendor-targeted component as a broken reference.

But #2006 is open on the same two files for the same issue (engine#2000) and says the same thing in the context of the ai.onnx-only bullet. As they stand
the two will conflict textually, and if both land the paragraph appears twice. One should close, or one should be rebased onto the other and reduced to the half
it adds (*_strategy.yaml's four domain names is the part #2006 does not carry). Flagging it on both so the choice is visible; the content of each is correct.