fix: repair stale refs and restore deleted compatibility-matrix files

Stale references fixed after main.go and heavy-docs reorganization:
- README.md: 'go build .' -> 'go build ./cmd/hawk' (2 spots)
- README.md: '# Architecture, research notes' -> 'docs/' description
- docs/architecture.md: 'main.go at root' -> 'cmd/hawk/main.go' + 'main: ./cmd/hawk'
- docs/compatibility.md: self-ref './docs/platform-capabilities.json' -> './platform-capabilities.json'
- Makefile: VERSIONING.md GitHub URL -> docs/versioning.md
- scripts/verify-developer-path.sh: 'go build .' -> 'go build ./cmd/hawk'
- scripts/e2e-macos.sh: 'go build -o hawk .' -> 'go build -o hawk ./cmd/hawk'

Restored files (Makefile compat-test target was broken):
- testdata/compatibility-matrix.json
- testdata/compatibility-matrix.schema.json

Author: Patel230

Makefile

@@ -10,7 +10,7 @@ MAIN_PKG  := ./cmd/hawk
 
 # ---------------------------------------------------------------------------
 # Versioning — sourced from VERSION file; falls back to git describe.
-# See https://github.com/GrayCodeAI/hawk/blob/main/VERSIONING.md.
+# See https://github.com/GrayCodeAI/hawk/blob/main/docs/versioning.md.
 # ---------------------------------------------------------------------------
 VERSION ?= $(shell cat VERSION 2>/dev/null | head -n1 | tr -d '[:space:]' || git describe --tags --always --dirty 2>/dev/null || echo "dev")
 COMMIT  := $(shell git rev-parse --short HEAD 2>/dev/null || echo "none")

README.md

@@ -64,7 +64,7 @@ go install github.com/GrayCodeAI/hawk@latest
 curl -fsSL https://raw.githubusercontent.com/GrayCodeAI/hawk/main/install.sh | sh
 
 # From source
-git clone https://github.com/GrayCodeAI/hawk && cd hawk && go build .
+git clone https://github.com/GrayCodeAI/hawk && cd hawk && go build ./cmd/hawk
 ```
 
 ## Features
@@ -220,7 +220,7 @@ hawk/
 │   ├── bridge/             # External bridges (sight, inspect, sessioncapture)
 │   ├── provider/           # Provider routing
 │   └── system/             # Bus, cron, retention, shutdown
-├── docs/                   # Architecture, research notes
+├── docs/                   # Architecture, security, integration docs
 └── testdata/               # Test fixtures
 ```
 
@@ -255,7 +255,7 @@ You may keep a **personal** parent **`go.work`** that lists alternate clones on
 ### Build & Test
 
 ```bash
-go build .                    # Build binary
+go build ./cmd/hawk           # Build binary
 go test -race ./...           # Run all tests with race detector
 make ci                       # Run full CI suite (lint, test, security)
 make cover                    # Generate coverage report

docs/architecture.md

@@ -22,9 +22,9 @@ hawk is an AI-powered coding agent for the terminal. It reads codebases, writes
 
 ```
 hawk/
-├── main.go                    ⚡ Entry point — calls cmd.Execute()
 ├── api/openapi.yaml           📜 Daemon REST API contract (OpenAPI 3.1)
 ├── cmd/                       🖥️ Cobra CLI commands (200+ files)
+│   ├── hawk/main.go           ⚡ Entry point — calls cmd.Execute()
 │   ├── root.go                ⚙️ Root command, flag definitions
 │   ├── daemon.go              🔮 Daemon start/stop/status
 │   ├── chat.go                💬 Interactive TUI chat
@@ -111,7 +111,7 @@ Tool Call → 🛡️ Guardian (rules DSL) → 🧱 Boundary Checker → 👤 Us
 
 | Decision | Rationale |
 |----------|-----------|
-| `main.go` at root | Intentional — goreleaser builds with `main: ./` producing `hawk` binary |
+| `cmd/hawk/main.go` entry point | Standard Go layout — goreleaser builds with `main: ./cmd/hawk` producing `hawk` binary |
 | `cmd/` is CLI library | Not a binary sub-directory — holds 200+ cobra command files |
 | Zero CGO | Pure Go, cross-compilable. Tree-sitter is optional |
 | `internal/` is private | Other repos import `shared/types/` only |

docs/compatibility.md

@@ -6,7 +6,7 @@ question: *which combinations of versions are actually tested together?*
 
 The answer lives in [`testdata/compatibility-matrix.json`](./testdata/compatibility-matrix.json).
 
-Platform/provider capability metadata is separate: [`platform-capabilities.json`](./docs/platform-capabilities.json).
+Platform/provider capability metadata is separate: [`platform-capabilities.json`](./platform-capabilities.json).
 
 ## What it records
 

scripts/e2e-macos.sh

@@ -12,7 +12,7 @@ fail() { FAIL=$((FAIL+1)); echo "  FAIL: $1"; }
 # Ensure binary exists
 if [ ! -f ./hawk ]; then
     echo "Building hawk..."
-    go build -o hawk .
+    go build -o hawk ./cmd/hawk
 fi
 
 echo "=== macOS E2E Tests ==="

scripts/verify-developer-path.sh

@@ -15,7 +15,7 @@ go test ./internal/tool/ -run 'IsSensitivePath' -count=1
 
 echo "== developer path CLI =="
 BIN="${DEV_PATH_HAWK_BIN:-/tmp/hawk-path-verify}"
-go build -mod=readonly -o "$BIN" .
+go build -mod=readonly -o "$BIN" ./cmd/hawk
 set +o pipefail
 "$BIN" path >/dev/null 2>&1 || true
 set -o pipefail

testdata/compatibility-matrix.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "./compatibility-matrix.schema.json",
+  "description": "Cross-repo compatibility tracking for GrayCodeAI repositories. Each `matrix` entry records a combination of component versions that have been tested together. CI runs the matrix on a schedule and on PR to ensure released components stay compatible.",
+  "version": "1",
+  "updated": "2026-06-02",
+  "components": [
+    "hawk",
+    "hawk-sdk-go",
+    "hawk-sdk-python",
+    "eyrie",
+    "sight",
+    "inspect",
+    "tok",
+    "yaad",
+    "trace"
+  ],
+  "dependencies": {
+    "hawk":            ["eyrie", "sight", "inspect", "tok"],
+    "hawk-sdk-go":     ["hawk"],
+    "hawk-sdk-python": ["hawk"],
+    "sight":           ["hawk", "eyrie"],
+    "inspect":         ["hawk"],
+    "trace":           [],
+    "tok":             ["hawk"],
+    "yaad":            [],
+    "eyrie":           []
+  },
+  "matrices": [
+    {
+      "name": "stable",
+      "description": "Latest tested-together stable combination across the eco. This is what new users get when installing.",
+      "components": {
+        "hawk":            "0.2.0",
+        "hawk-sdk-go":     "0.2.0",
+        "hawk-sdk-python": "0.2.0",
+        "eyrie":           "0.2.0",
+        "sight":           "0.2.0",
+        "inspect":         "0.2.0",
+        "tok":             "0.2.0",
+        "yaad":            "0.2.0",
+        "trace":           "0.2.0"
+      }
+    },
+    {
+      "name": "next",
+      "description": "Combination that the upcoming release will ship — kept up to date by release-please as components advance. Tested in CI on every PR.",
+      "components": {
+        "hawk":            "main",
+        "hawk-sdk-go":     "main",
+        "hawk-sdk-python": "main",
+        "eyrie":           "main",
+        "sight":           "main",
+        "inspect":         "main",
+        "tok":             "main",
+        "yaad":            "main",
+        "trace":           "main"
+      }
+    }
+  ]
+}

testdata/compatibility-matrix.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/GrayCodeAI/hawk/blob/main/compatibility-matrix.schema.json",
+  "title": "GrayCodeAI compatibility matrix",
+  "description": "Schema for compatibility-matrix.json — records which combinations of component versions are tested together.",
+  "type": "object",
+  "required": ["version", "components", "dependencies", "matrices"],
+  "properties": {
+    "$schema":     { "type": "string" },
+    "description": { "type": "string" },
+    "version":     { "type": "string", "description": "Schema version of this file (independent of any component version)." },
+    "updated":     { "type": "string", "format": "date" },
+    "components": {
+      "type": "array",
+      "description": "Canonical list of component (repo) names in the eco.",
+      "items": { "type": "string" },
+      "uniqueItems": true,
+      "minItems": 1
+    },
+    "dependencies": {
+      "type": "object",
+      "description": "Per-component dependency list — which other eco components a given one consumes. Drives test ordering and impact analysis.",
+      "additionalProperties": {
+        "type": "array",
+        "items": { "type": "string" }
+      }
+    },
+    "matrices": {
+      "type": "array",
+      "description": "Named version combinations that are tested together.",
+      "items": {
+        "type": "object",
+        "required": ["name", "components"],
+        "properties": {
+          "name":        { "type": "string" },
+          "description": { "type": "string" },
+          "components": {
+            "type": "object",
+            "description": "Map of component name → version. Use `main` to mean the latest commit on the main branch (tested every PR).",
+            "additionalProperties": { "type": "string" }
+          }
+        }
+      },
+      "minItems": 1
+    }
+  }
+}