feat: release workflow, godoc, and --version flag

- Add .github/workflows/release.yml: builds cross-platform binaries
  (linux/darwin/windows × amd64/arm64) and publishes them to GitHub
  Releases whenever a vX.Y.Z tag is pushed
- Add --version flag to CLI; version injected at build time via
  -ldflags "-X main.version=vX.Y.Z"
- Add package-level doc comments to parser and rules packages
- Add rules/doc.go listing all eight built-in rules

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: Haleh

.github/workflows/release.yml

@@ -0,0 +1,55 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Build and publish
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
+            goarch: arm64
+          - goos: darwin
+            goarch: amd64
+          - goos: darwin
+            goarch: arm64
+          - goos: windows
+            goarch: amd64
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+          cache: true
+
+      - name: Build binary
+        env:
+          GOOS: ${{ matrix.goos }}
+          GOARCH: ${{ matrix.goarch }}
+          CGO_ENABLED: '0'
+        run: |
+          EXT=""
+          [ "$GOOS" = "windows" ] && EXT=".exe"
+          OUTPUT="pgexplain-${{ github.ref_name }}-${GOOS}-${GOARCH}${EXT}"
+          go build -trimpath -ldflags="-s -w -X main.version=${{ github.ref_name }}" \
+            -o "$OUTPUT" ./cmd/pgexplain
+          echo "ASSET=$OUTPUT" >> "$GITHUB_ENV"
+
+      - name: Upload binary to release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: ${{ env.ASSET }}
+          generate_release_notes: true

cmd/pgexplain/main.go

@@ -22,15 +22,24 @@ import (
 	"github.com/Bright98/pgexplain/rules"
 )
 
+// version is set at build time via -ldflags "-X main.version=vX.Y.Z".
+var version = "dev"
+
 // valueColumn is the character position where field values start in text output.
 // It equals the width of the widest label prefix: "  suggestion: " = 14.
 const valueColumn = 14
 
 func main() {
 	format := flag.String("format", "text", `Output format: "text" (default) or "json"`)
+	showVersion := flag.Bool("version", false, "Print version and exit")
 	flag.Usage = usage
 	flag.Parse()
 
+	if *showVersion {
+		fmt.Println(version)
+		return
+	}
+
 	data, err := readInput(flag.Args())
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "pgexplain: %v\n", err)

parser/parser.go

@@ -1,3 +1,14 @@
+// Package parser decodes the JSON produced by PostgreSQL's
+// EXPLAIN (FORMAT JSON) and EXPLAIN (ANALYZE, FORMAT JSON) commands
+// into a typed Go plan tree.
+//
+// The entry point is [Parse], which accepts the raw JSON bytes and returns
+// a [Plan] whose root node is a [Node]. Each Node may have child nodes in
+// its Plans slice, forming the full plan tree.
+//
+// Fields populated only when ANALYZE is used (ActualRows, ActualLoops,
+// HeapFetches, SortSpaceType, etc.) are exposed as pointers so callers can
+// distinguish "absent" from "zero".
 package parser
 
 import (

rules/doc.go

@@ -0,0 +1,19 @@
+// Package rules provides built-in advisor rules for pgexplain.
+//
+// Each rule implements the [advisor.Rule] interface and is constructed via a
+// factory function (e.g. [SeqScan], [SortSpill]). Rules accept optional
+// functional options to override default thresholds.
+//
+// # Built-in rules
+//
+//   - [SeqScan]               — sequential scan on a large table
+//   - [RowEstimateMismatch]   — plan row estimate far from actual rows
+//   - [HashJoinSpill]         — hash join batch count > 1 (disk spill)
+//   - [NestedLoopLarge]       — nested-loop join over a large outer side
+//   - [MissingIndexOnlyScan]  — index-only scan with high heap-fetch ratio
+//   - [SortSpill]             — sort spilled to disk (external merge)
+//   - [TopNHeapsort]          — top-N heapsort over a full sequential scan
+//   - [ParallelNotLaunched]   — fewer parallel workers launched than planned
+//
+// All rules are safe for concurrent use.
+package rules