Alex9001 · Alex9001 · Sep 1, 2026 · Sep 1, 2026
diff --git a/CONTRIBUTING.md → .github/CONTRIBUTING.md b/CONTRIBUTING.md → .github/CONTRIBUTING.md
@@ -23,20 +23,21 @@ Ninja, Qt 6 Core/Gui/Widgets/Test, and a C++17 compiler.
 ```sh
 git clone https://github.com/Alex9001/whodis.git
 cd whodis
-go test -race ./...
-go vet ./...
-go test ./... -run '^$' -bench . -benchtime=100ms
+go -C v2 test -race ./...
+go -C v2 vet ./...
+go -C v2 test ./... -run '^$' -bench . -benchtime=100ms
 ```
 
-The root package and `audit` package include native Go fuzz targets for subject
-and endpoint parsing, registration text parsing, DNS wire normalization,
-rendering, and policy/snapshot imports. Run one locally with, for example:
+The module's root package and `audit` package include native Go fuzz targets
+for subject and endpoint parsing, registration text parsing, DNS wire
+normalization, rendering, and policy/snapshot imports. Run one locally with,
+for example:
 
 ```sh
-go test . -run '^$' -fuzz=FuzzSubjectAndEndpointParsing -fuzztime=30s
+go -C v2 test . -run '^$' -fuzz=FuzzSubjectAndEndpointParsing -fuzztime=30s
 ```
 
-See [desktop/README.md](desktop/README.md) for GUI build instructions. Keep
+See [desktop/README.md](../desktop/README.md) for GUI build instructions. Keep
 network-dependent behavior behind injectable providers or local fixtures;
 tests must not consume public registry or Globalping quota.
 

diff --git a/SECURITY.md → .github/SECURITY.md b/SECURITY.md → .github/SECURITY.md
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -1,7 +1,7 @@
 version: 2
 updates:
   - package-ecosystem: gomod
-    directory: /
+    directory: /v2
     schedule:
       interval: monthly
     groups:

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -51,6 +51,15 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
+      - name: Validate Go module layout
+        shell: bash
+        run: |
+          set -euo pipefail
+          test "$(go -C v2 list -m)" = "github.com/Alex9001/whodis/v2"
+          test ! -e go.mod
+          test ! -e go.sum
+          test -z "$(find . -maxdepth 1 -type f -name '*.go' -print -quit)"
       - name: Validate Unix installer syntax
         run: |
           sh -n scripts/install.sh
@@ -144,18 +153,18 @@ jobs:
             echo "installer accepted a corrupted archive" >&2
             exit 1
           fi
-      - run: go vet ./...
+      - run: go -C v2 vet ./...
       - name: Validate GitHub Actions workflows
-        run: go run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7 -config-file .github/actionlint.yaml .github/workflows/*.yml
+        run: go -C v2 run github.com/rhysd/actionlint/cmd/actionlint@v1.7.7 -config-file "$GITHUB_WORKSPACE/.github/actionlint.yaml" "$GITHUB_WORKSPACE"/.github/workflows/*.yml
       - name: Run staticcheck
-        run: go run honnef.co/go/tools/cmd/staticcheck@v0.8.1 ./...
+        run: go -C v2 run honnef.co/go/tools/cmd/staticcheck@v0.8.1 ./...
       - name: Enforce Go complexity guardrails
         run: scripts/check-complexity.sh go
-      - run: go test -race ./...
+      - run: go -C v2 test -race ./...
       - name: Run Go security static analysis
-        run: go run github.com/securego/gosec/v2/cmd/gosec@v2.28.0 -exclude-generated -quiet ./...
+        run: go -C v2 run github.com/securego/gosec/v2/cmd/gosec@v2.28.0 -exclude-generated -quiet ./...
       - name: Scan Go dependencies and reachable code
-        run: go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
+        run: go -C v2 run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
 
   powershell-installer:
     name: Test Windows and PowerShell installer
@@ -165,8 +174,9 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
       - name: Test Windows build
-        run: go test ./...
+        run: go -C v2 test ./...
       - name: Parse installer
         shell: pwsh
         run: |
@@ -213,6 +223,7 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
       - name: Install Qt build dependencies
         run: |
           sudo apt-get update
@@ -267,6 +278,7 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
       - name: Install GoReleaser
         uses: goreleaser/goreleaser-action@f06c13b6b1a9625abc9e6e439d9c05a8f2190e94 # v7
         with:
@@ -304,12 +316,13 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
       - name: Cross-build pure-Go CLI
         env:
           CGO_ENABLED: 0
           GOOS: ${{ matrix.goos }}
           GOARCH: ${{ matrix.goarch }}
-        run: go build -trimpath ./cmd/whodis
+        run: go -C v2 build -trimpath ./cmd/whodis
 
   container-build:
     name: Build OCI image

diff --git a/.github/workflows/maintenance.yml b/.github/workflows/maintenance.yml
@@ -30,17 +30,18 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
-      - run: go test -race ./...
+          cache-dependency-path: v2/go.sum
+      - run: go -C v2 test -race ./...
       - name: Scan dependencies and reachable code
-        run: go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
+        run: go -C v2 run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
       - name: Run bounded parser and renderer fuzzing
         run: |
-          go test . -run='^$' -fuzz=FuzzSubjectAndEndpointParsing -fuzztime=20s
-          go test . -run='^$' -fuzz=FuzzParseTargetASPrefix -fuzztime=20s
-          go test . -run='^$' -fuzz=FuzzRegistrationTextParsers -fuzztime=20s
-          go test . -run='^$' -fuzz=FuzzDNSWireNormalization -fuzztime=20s
-          go test . -run='^$' -fuzz=FuzzReportRendering -fuzztime=20s
-          go test ./audit -run='^$' -fuzz=FuzzPolicyAndSnapshotImports -fuzztime=20s
+          go -C v2 test . -run='^$' -fuzz=FuzzSubjectAndEndpointParsing -fuzztime=20s
+          go -C v2 test . -run='^$' -fuzz=FuzzParseTargetASPrefix -fuzztime=20s
+          go -C v2 test . -run='^$' -fuzz=FuzzRegistrationTextParsers -fuzztime=20s
+          go -C v2 test . -run='^$' -fuzz=FuzzDNSWireNormalization -fuzztime=20s
+          go -C v2 test . -run='^$' -fuzz=FuzzReportRendering -fuzztime=20s
+          go -C v2 test ./audit -run='^$' -fuzz=FuzzPolicyAndSnapshotImports -fuzztime=20s
 
   live-compatibility:
     name: Advisory live protocol compatibility
@@ -51,8 +52,9 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
       - name: Build Whodis
-        run: go build -trimpath -o "$RUNNER_TEMP/whodis" ./cmd/whodis
+        run: go -C v2 build -trimpath -o "$RUNNER_TEMP/whodis" ./cmd/whodis
       - name: Check public registration routing
         run: |
           "$RUNNER_TEMP/whodis" example.com --json --timeout 30s | jq --exit-status '.schema_version == 5'

diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
@@ -43,6 +43,7 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
       - name: Install build dependencies
         run: |
           sudo apt-get update
@@ -168,6 +169,7 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
       - uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 # v1
         with:
           arch: ${{ matrix.msvc_arch }}
@@ -234,6 +236,7 @@ jobs:
       - uses: actions/setup-go@b7ad1dad31e06c5925ef5d2fc7ad053ef454303e # v7
         with:
           go-version: ${{ env.GO_VERSION }}
+          cache-dependency-path: v2/go.sum
       - uses: jurplel/install-qt-action@48d3ad6db93f3627c8ee7a0454bc6f3744f7e730 # v4.3.1
         with:
           version: '6.10.2'
@@ -276,9 +279,9 @@ jobs:
           mv "$app" build-gui/bin/Whodis.app
           app=build-gui/bin/Whodis.app
           mkdir -p "$app/Contents/Helpers" "$app/Contents/Resources"
-          CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go build -trimpath \
+          CGO_ENABLED=0 GOOS=darwin GOARCH=amd64 go -C v2 build -trimpath \
             -ldflags="-s -w -X main.version=$version -X github.com/Alex9001/whodis/v2.version=$version" -o /tmp/whodis-engine-amd64 ./cmd/whodis-gui-engine
-          CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go build -trimpath \
+          CGO_ENABLED=0 GOOS=darwin GOARCH=arm64 go -C v2 build -trimpath \
             -ldflags="-s -w -X main.version=$version -X github.com/Alex9001/whodis/v2.version=$version" -o /tmp/whodis-engine-arm64 ./cmd/whodis-gui-engine
           lipo -create /tmp/whodis-engine-amd64 /tmp/whodis-engine-arm64 \
             -output "$app/Contents/Helpers/whodis-gui-engine"
@@ -323,6 +326,7 @@ jobs:
         with:
           go-version: ${{ env.GO_VERSION }}
           cache: true
+          cache-dependency-path: v2/go.sum
       - uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           pattern: whodis-gui-*
@@ -334,11 +338,11 @@ jobs:
           syft-version: ${{ env.SYFT_VERSION }}
       - name: Vet, test, and analyze release source
         run: |
-          go vet ./...
-          go test -race ./...
-          go run honnef.co/go/tools/cmd/staticcheck@v0.8.1 ./...
-          go run github.com/securego/gosec/v2/cmd/gosec@v2.28.0 -exclude-generated -quiet ./...
-          go run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
+          go -C v2 vet ./...
+          go -C v2 test -race ./...
+          go -C v2 run honnef.co/go/tools/cmd/staticcheck@v0.8.1 ./...
+          go -C v2 run github.com/securego/gosec/v2/cmd/gosec@v2.28.0 -exclude-generated -quiet ./...
+          go -C v2 run golang.org/x/vuln/cmd/govulncheck@v1.7.0 ./...
       - name: List unsigned GUI assets
         run: |
           echo 'Desktop packages are intentionally unsigned.'

diff --git a/.goreleaser.yaml b/.goreleaser.yaml
@@ -2,12 +2,16 @@ version: 2
 
 project_name: whodis
 
+gomod:
+  dir: ./v2
+
 before:
   hooks:
     - ./scripts/collect-go-licenses.sh .release-assets/go-licenses
 
 builds:
   - id: whodis
+    dir: ./v2
     main: ./cmd/whodis
     binary: whodis
     env:
@@ -39,7 +43,8 @@ archives:
           - zip
     files:
       - README.md
-      - MIGRATING_TO_V2.md
+      - src: docs/MIGRATING_TO_V2.md
+        dst: MIGRATING_TO_V2.md
       - LICENSE
       - src: ./.release-assets/go-licenses/*
         dst: Go-Licenses
@@ -75,7 +80,7 @@ nfpms:
         dst: /usr/share/licenses/whodis/LICENSE
       - src: ./README.md
         dst: /usr/share/doc/whodis/README.md
-      - src: ./MIGRATING_TO_V2.md
+      - src: ./docs/MIGRATING_TO_V2.md
         dst: /usr/share/doc/whodis/MIGRATING_TO_V2.md
       - src: ./.release-assets/go-licenses
         dst: /usr/share/licenses/whodis/third-party

diff --git a/Dockerfile b/Dockerfile
@@ -1,11 +1,11 @@
 FROM golang:1.27-alpine AS build
 
 WORKDIR /src
-COPY go.mod go.sum ./
-RUN go mod download
+COPY v2/go.mod v2/go.sum ./v2/
+RUN go -C v2 mod download
 COPY . .
 ARG VERSION=dev
-RUN CGO_ENABLED=0 go build -trimpath \
+RUN CGO_ENABLED=0 go -C v2 build -trimpath \
     -ldflags="-s -w -X main.version=${VERSION} -X github.com/Alex9001/whodis/v2.version=${VERSION}" \
     -o /out/whodis ./cmd/whodis
 RUN ./scripts/collect-go-licenses.sh /out/licenses/third-party && cp LICENSE /out/licenses/LICENSE

diff --git a/README.md b/README.md
@@ -595,20 +595,24 @@ The native GUI's private newline-delimited JSON-RPC protocol is version 5 and
 carries schema-v5 reports through the same operation engine as the CLI, plus
 progress, cancellation, the research-provider catalog, short-lived in-memory
 result tokens, and exports. See
-[MIGRATING_TO_V2.md](MIGRATING_TO_V2.md) when upgrading an embedded v1 client.
+[v2 migration guide](docs/MIGRATING_TO_V2.md) when upgrading an embedded v1
+client.
 
 ## Development and release integrity
 
 ```bash
 git clone https://github.com/Alex9001/whodis.git
 cd whodis
-go test -race ./...
-go vet ./...
+go -C v2 test -race ./...
+go -C v2 vet ./...
 scripts/check-complexity.sh go
-go test ./... -run '^$' -bench . -benchtime=100ms
-go run ./cmd/whodis example.com
+go -C v2 test ./... -run '^$' -bench . -benchtime=100ms
+go -C v2 run ./cmd/whodis example.com
 ```
 
+The Go module uses the standard `v2/` major-version directory. Its public
+module path remains `github.com/Alex9001/whodis/v2`.
+
 The desktop build additionally needs CMake, Ninja, Qt 6 Core/Gui/Widgets/Test,
 and a C++17 compiler; source builds require Go 1.25 or newer. With Clang and
 Clang-Tidy installed, `scripts/check-complexity.sh all` also enforces the Go

diff --git a/desktop/CMakeLists.txt b/desktop/CMakeLists.txt
@@ -61,7 +61,7 @@ set_target_properties(whodis-gui PROPERTIES
 
 find_program(GO_EXECUTABLE go REQUIRED)
 file(GLOB_RECURSE WHODIS_ENGINE_GO_SOURCES CONFIGURE_DEPENDS
-    "${CMAKE_CURRENT_SOURCE_DIR}/../*.go"
+    "${CMAKE_CURRENT_SOURCE_DIR}/../v2/*.go"
 )
 if(WIN32)
     set(WHODIS_ENGINE_FILENAME "whodis-gui-engine.exe")
@@ -75,11 +75,11 @@ add_custom_command(
             "-ldflags=-s -w -X main.version=${WHODIS_VERSION} -X github.com/Alex9001/whodis/v2.version=${WHODIS_VERSION}"
             -o "${WHODIS_ENGINE_OUTPUT}"
             ./cmd/whodis-gui-engine
-    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/.."
+    WORKING_DIRECTORY "${CMAKE_CURRENT_SOURCE_DIR}/../v2"
     DEPENDS
         ${WHODIS_ENGINE_GO_SOURCES}
-        "${CMAKE_CURRENT_SOURCE_DIR}/../go.mod"
-        "${CMAKE_CURRENT_SOURCE_DIR}/../go.sum"
+        "${CMAKE_CURRENT_SOURCE_DIR}/../v2/go.mod"
+        "${CMAKE_CURRENT_SOURCE_DIR}/../v2/go.sum"
     VERBATIM
 )
 add_custom_target(whodis-gui-engine ALL DEPENDS "${WHODIS_ENGINE_OUTPUT}")

diff --git a/desktop/packaging/THIRD_PARTY_NOTICES.md b/desktop/packaging/THIRD_PARTY_NOTICES.md
@@ -21,4 +21,4 @@ licenses: miekg/dns and the Go extended libraries (BSD), quic-go and qpack
 (MIT), ProjectDiscovery wappalyzergo (MIT), dnscrypt and dnsstamps (Unlicense),
 go-runewidth (MIT), and yaml.v3 (MIT/Apache-style notice). Their exact license
 texts are bundled in the `Go-Licenses` directory; versions are recorded by
-`go.mod`, `go.sum`, and each release's generated SBOM.
+`v2/go.mod`, `v2/go.sum`, and each release's generated SBOM.
diff --git a/desktop/resources/resources.qrc b/desktop/resources/resources.qrc
@@ -3,15 +3,15 @@
     <file alias="whodis.png">whodis-512.png</file>
   </qresource>
   <qresource prefix="/help">
-    <file alias="catalog.json">../../internal/helpdocs/catalog.json</file>
-    <file alias="topics/overview.md">../../internal/helpdocs/topics/overview.md</file>
-    <file alias="topics/registration.md">../../internal/helpdocs/topics/registration.md</file>
-    <file alias="topics/dns.md">../../internal/helpdocs/topics/dns.md</file>
-    <file alias="topics/diagnose.md">../../internal/helpdocs/topics/diagnose.md</file>
-    <file alias="topics/investigate.md">../../internal/helpdocs/topics/investigate.md</file>
-    <file alias="topics/batch.md">../../internal/helpdocs/topics/batch.md</file>
-    <file alias="topics/snapshots.md">../../internal/helpdocs/topics/snapshots.md</file>
-    <file alias="topics/privacy.md">../../internal/helpdocs/topics/privacy.md</file>
-    <file alias="topics/troubleshooting.md">../../internal/helpdocs/topics/troubleshooting.md</file>
+    <file alias="catalog.json">../../v2/internal/helpdocs/catalog.json</file>
+    <file alias="topics/overview.md">../../v2/internal/helpdocs/topics/overview.md</file>
+    <file alias="topics/registration.md">../../v2/internal/helpdocs/topics/registration.md</file>
+    <file alias="topics/dns.md">../../v2/internal/helpdocs/topics/dns.md</file>
+    <file alias="topics/diagnose.md">../../v2/internal/helpdocs/topics/diagnose.md</file>
+    <file alias="topics/investigate.md">../../v2/internal/helpdocs/topics/investigate.md</file>
+    <file alias="topics/batch.md">../../v2/internal/helpdocs/topics/batch.md</file>
+    <file alias="topics/snapshots.md">../../v2/internal/helpdocs/topics/snapshots.md</file>
+    <file alias="topics/privacy.md">../../v2/internal/helpdocs/topics/privacy.md</file>
+    <file alias="topics/troubleshooting.md">../../v2/internal/helpdocs/topics/troubleshooting.md</file>
   </qresource>
 </RCC>
diff --git a/MIGRATING_TO_V2.md → docs/MIGRATING_TO_V2.md b/MIGRATING_TO_V2.md → docs/MIGRATING_TO_V2.md
diff --git a/packaging/aur-gui/PKGBUILD.in b/packaging/aur-gui/PKGBUILD.in
@@ -15,7 +15,7 @@ sha256sums=('@SHA256@')
 
 prepare() {
   cd "whodis_${pkgver}"
-  go mod download
+  go -C v2 mod download
 }
 
 build() {
@@ -30,7 +30,7 @@ build() {
 
 check() {
   cd "whodis_${pkgver}"
-  go test ./...
+  go -C v2 test ./...
   QT_QPA_PLATFORM=offscreen ctest --test-dir build-gui --output-on-failure
 }