docs: move the recipe and version descriptions with the behaviour

Assisted-by: GLM 5.3 Flash

docs/DEVELOPMENT.md

@@ -13,45 +13,71 @@ Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrb
 ```sh
 git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
 cd gasm-devkit
-just install   # go mod download
-just build     # go vet + gofmt, must pass with zero output
-just test      # full suite, race detector, 80 % coverage gate
+just build     # compile bin/gasm, zero errors and zero warnings
+just gates     # build, fmt-check, vet, test, race: the definition of done
 ```
 
 ## Just Recipes
 
-### `just install`
-
-`go mod download`.  The only module dependency, `golang.org/x/arch`, is
-used in tests only.
-
 ### `just build`
 
-Runs `go vet ./...` and checks `gofmt -l .` produces no output. This is
-the minimum bar before any commit.
+Compiles `bin/gasm` with `CGO_ENABLED=0` and stripped symbols. Zero
+errors, zero warnings. This is the minimum bar before any commit.
+
+### `just gates`
+
+The definition of done, in one command: `build`, `fmt-check`, `vet`,
+`test` and `race`, in that order. Run it once per task, never per edit;
+`just unit` is the one that runs after every edit.
 
 ### `just test`
 
 ```sh
-go test -race -count=1 ./...
+go test -count=1 -timeout 30m -coverprofile=coverage.out \
+    -coverpkg=./arch/...,./asm/...,./ast/...,./disasm/...,./format/...,./lexer/...,./lint/...,./lsp/...,./parser/...,./token/...,./verify/... \
+    ./...
 ```
 
-Plus a coverage run over the ten analysable packages (arch, asm, ast,
-format, lexer, lint, lsp, parser, token, verify; `debug` and `cmd/gasm`
-need hardware or are CLI glue) and an `awk` gate that fails if total
-coverage is below 80 %.
+The whole suite runs (`-count=1`, so no cached pass counts), which keeps
+the packages that need hardware and the CLI glue under the gate. The
+coverage floor is computed over the product packages only (arch, asm,
+ast, disasm, format, lexer, lint, lsp, parser, token, verify; `debug`
+traces a live process and `cmd/gasm` is CLI glue) and fails if the total
+is below 80 %.
 
-### `just fmt`
+### `just race`
+
+The same suite under the race detector. The expensive one, so it runs
+once, inside `gates`.
+
+### `just unit`
 
 ```sh
-gofmt -w .
+just unit ./asm/ TestVexGroundTruth
 ```
 
-Run after editing any Go source. The output must be idempotent.
+Fast, cached, scoped run for iterating: no race, no coverage, so an
+unchanged package reports instantly.
+
+### `just fuzz <target> <pkg>`
+
+Time-boxed fuzz of one target in one package; the package is required,
+because `go test -fuzz` refuses more than one. Seed corpora run as plain
+tests in `unit` and `test`. Never a gate.
+
+### `just bench`
+
+Benchmarks (`-benchmem -count=5`). On an idle machine only.
+
+### `just fmt`, `just fmt-check`, `just vet`
+
+`fmt` formats in place. `fmt-check` prints nothing when everything is
+formatted, which is the shape the CI step wants. `vet` runs both static
+gates: `go vet` and `go fix -diff`.
 
 ### `just run -- <args>`
 
-Runs the CLI via `go run` with the version string stamped:
+Runs the CLI via `go run -buildvcs=true`:
 
 ```sh
 just run -- lint kernel_amd64.s
@@ -59,10 +85,23 @@ just run -- fmt -w kernel_amd64.s
 just run -- verify --ground-truth kernel_amd64.s
 ```
 
-### `just install-bin`
+### `just install`
 
-Installs the `gasm` binary into `$GOBIN` with the release version
-embedded via `-ldflags "-X main.version=..."`.
+Builds and copies the `gasm` binary into `~/.local/bin` (`BINDIR`
+overrides the destination).
+
+### `just uninstall`, `just clean`
+
+`uninstall` removes the installed binary from `bindir`. `clean` removes
+the build artefacts: `bin/` and `coverage.out`.
+
+## Version reporting
+
+The version is never injected. `gasm --version` prints what the
+toolchain recorded in the build information: the tag on a tagged
+checkout, a pseudo-version naming the commit below one, `+dirty` on a
+dirty tree, and `(devel)` outside version control. There is no
+`-ldflags "-X"` anywhere and no version constant in the source.
 
 ### `just gen`
 
@@ -91,7 +130,7 @@ go test -run TestFuzzWideCopy ./verify/
 not work with `go run`; install first:
 
 ```sh
-just install-bin
+just install
 gasm debug --func decodeBlockAVX2 path/to/kernel_amd64.s
 ```