Running your checkout

Three things are called dqx, they all print the same version, and only one of them is running at a time. That is where an afternoon goes: an edit that "does nothing" is usually an edit to a checkout while the shell is running the release.

Ask, at any point:

dqx version --where

1.0.0
running: /Users/dev/dockers/dq-tools-next/dist/dqx  (a build of a checkout)
`bun run build` updates it. `bun run link:dev` runs the sources instead
back to the release: `bun run link:release`

The three, and how to switch

	what runs	when to use it
bun run link	dist/dqx, the compiled checkout	what a colleague will get - the compiled path, embedded assets and all
bun run link:dev	src/cli.ts, through bun	working on it: an edit is live, nothing to rebuild
bun run link:release	the installed release	checking whether a bug is yours or was already there

All three put dqx in the first writable directory on your PATH - ~/.local/bin on most machines, the same place install.sh uses.

Your installed release is not thrown away. The first bun run link moves it aside as dqx-released and bun run link:release puts it back, so switching costs nothing and needs no network. If there is nothing to put back, the installer says so and prints the curl line.

Which one is a colleague running?

dqx version --where answers that too, and is worth asking before believing a bug report. A release older than this feature answers unknown option '--where', which is its own kind of answer.

While you work

bun run link:dev      # once
bun test --watch      # the loop
bun run test:gate     # what CI runs: build, tests, and the coverage gate

bun run dev -- <args> runs the sources once without linking anything, for when you only want to see what one command does.

The dashboard, against a fleet that does not exist

dqx dashboard --demo          # site/screens/fleet.demo.json
dqx dashboard --demo my.json  # your own

Six fictional projects from a file instead of this machine: one running multi-site project, a stopped single, a project on a v1 config, a --temp clone, one whose database disagrees with its image, and a directory dqx has not adopted. Read only, always, and the header says demo data.

It exists because the documentation's screenshots must never be taken from a real machine - the guard that keeps client names off the site reads text, and a screenshot carries names in pixels. It is also the only way to get all six of those cases on screen at once, which is what makes it useful for working on the UI.

The documentation's pictures and command output

bun run docs:screens          # every shot
bun run docs:screens gear     # just one
bun run docs:output           # the generated command output

docs:screens starts the demo dashboard, drives a browser and writes site/public/screens/*.png plus a hash per shot into site/screens/manifest.json. Every picture is repacked losslessly with oxipng (WebAssembly, no install needed), which makes it about 30 % smaller with the same pixels. It needs a browser, so it is local only: the pipeline has none, and what CI does instead is fail when a shot's hash no longer matches the dashboard.

When the gate says a screenshot is stale

Run bun run docs:screens and commit the pictures. If you have no browser, add "acceptedFor" with the hash the failure names and a one-line "why" to that shot in the manifest - it is a line the review can see, which is the point of it.

docs:output needs no browser: it renders dqx list and dqx doctor through the same pure functions the commands use, and captures the real --help. It runs as part of docs:build.