docs: refresh project documentation

bible-local/08-build-release.md

@@ -4,86 +4,74 @@
 
 Defined in `cmd/logpile/main.go`:
 
-| Flag | Default | Description |
-|------|---------|-------------|
+| Flag | Default | Purpose |
+|------|---------|---------|
 | `--port` | `8082` | HTTP server port |
-| `--file` | — | Reserved for archive preload (not active) |
-| `--version` | — | Print version and exit |
-| `--no-browser` | — | Do not open browser on start |
-| `--hold-on-crash` | `true` on Windows | Keep console open on fatal crash for debugging |
+| `--file` | empty | Preload archive file |
+| `--version` | `false` | Print version and exit |
+| `--no-browser` | `false` | Do not auto-open browser |
+| `--hold-on-crash` | `true` on Windows | Keep console open after fatal crash |
 
-## Build
+## Common commands
 
 ```bash
-# Local binary (current OS/arch)
 make build
-# Output: bin/logpile
-
-# Cross-platform binaries
 make build-all
-# Output:
-#   bin/logpile-linux-amd64
-#   bin/logpile-linux-arm64
-#   bin/logpile-darwin-amd64
-#   bin/logpile-darwin-arm64
-#   bin/logpile-windows-amd64.exe
-```
-
-Both `make build` and `make build-all` run `scripts/update-pci-ids.sh --best-effort`
-before compilation to sync `pci.ids` from the submodule.
-
-To skip PCI IDs update:
-```bash
-SKIP_PCI_IDS_UPDATE=1 make build
-```
-
-Build flags: `CGO_ENABLED=0` — fully static binary, no C runtime dependency.
-
-## PCI IDs submodule
-
-Source: `third_party/pciids` (git submodule → `github.com/pciutils/pciids`)
-Local copy embedded at build time: `internal/parser/vendors/pciids/pci.ids`
-
-```bash
-# Manual update
+make test
+make fmt
 make update-pci-ids
+```
 
-# Init submodule after fresh clone
+Notes:
+- `make build` outputs `bin/logpile`
+- `make build-all` builds the supported cross-platform binaries
+- `make build` and `make build-all` run `scripts/update-pci-ids.sh --best-effort` unless `SKIP_PCI_IDS_UPDATE=1`
+
+## PCI IDs
+
+Source submodule: `third_party/pciids`
+Embedded copy: `internal/parser/vendors/pciids/pci.ids`
+
+Typical setup after clone:
+
+```bash
 git submodule update --init third_party/pciids
 ```
 
-## Release process
+## Release script
+
+Run:
 
 ```bash
-scripts/release.sh
+./scripts/release.sh
 ```
 
-What it does:
+Current behavior:
+
 1. Reads version from `git describe --tags`
-2. Validates clean working tree (override: `ALLOW_DIRTY=1`)
-3. Sets stable `GOPATH` / `GOCACHE` / `GOTOOLCHAIN` env
-4. Creates `releases/{VERSION}/` directory
-5. Generates `RELEASE_NOTES.md` template if not present
-6. Builds `darwin-arm64` and `windows-amd64` binaries
-7. Packages all binaries found in `bin/` as `.tar.gz` / `.zip`
+2. Refuses a dirty tree unless `ALLOW_DIRTY=1`
+3. Sets stable Go cache/toolchain environment
+4. Creates `releases/{VERSION}/`
+5. Creates a release-notes template if missing
+6. Builds `darwin-arm64` and `windows-amd64`
+7. Packages any already-present binaries from `bin/`
 8. Generates `SHA256SUMS.txt`
-9. Prints next steps (tag, push, create release manually)
 
-Release notes template is created in `releases/{VERSION}/RELEASE_NOTES.md`.
+Important limitation:
+- `scripts/release.sh` does not run `make build-all` for you
+- if you want Linux or additional macOS archives in the release directory, build them before running the script
 
-## Running
+## Run locally
 
 ```bash
 ./bin/logpile
 ./bin/logpile --port 9090
 ./bin/logpile --no-browser
 ./bin/logpile --version
-./bin/logpile --hold-on-crash   # keep console open on crash (default on Windows)
 ```
 
 ## macOS Gatekeeper
 
-After downloading a binary, remove the quarantine attribute:
 ```bash
 xattr -d com.apple.quarantine /path/to/logpile-darwin-arm64
 ```