diff --git a/.github/workflows/validate-tap.yml b/.github/workflows/validate-tap.yml
new file mode 100644
index 0000000..0edd28a
--- /dev/null
+++ b/.github/workflows/validate-tap.yml
@@ -0,0 +1,17 @@
+name: Validate Tap
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Run tap consistency validation
+        run: ./scripts/validate_tap.sh
diff --git a/README.md b/README.md
index f2fb944..05fb23e 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,38 @@
 # homebrew-tap
-Homebrew tap for Grounds CLI
+
+Homebrew tap for Grounds CLI.
+
+## Install and upgrade
+
+Standard tap commands:
+
+```bash
+brew install groundsgg/tap/grounds
+brew upgrade groundsgg/tap/grounds
+brew info groundsgg/tap/grounds
+```
+
+Local file install (for maintainers):
+
+```bash
+brew install ./grounds.rb
+```
+
+## Repository layout
+
+- `grounds.rb`: Homebrew formula for Linux/macOS package installation.
+- `scripts/validate_tap.sh`: consistency checks for formula metadata.
+
+## Local validation
+
+Run the tap consistency validation:
+
+```bash
+./scripts/validate_tap.sh
+```
+
+Optional Homebrew audits:
+
+```bash
+brew audit --strict --formula ./grounds.rb
+```
diff --git a/scripts/validate_tap.sh b/scripts/validate_tap.sh
new file mode 100755
index 0000000..8e8b7d0
--- /dev/null
+++ b/scripts/validate_tap.sh
@@ -0,0 +1,57 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+FORMULA_PATH="grounds.rb"
+
+if [[ ! -f "${FORMULA_PATH}" ]]; then
+  echo "Validation failed: missing ${FORMULA_PATH}"
+  exit 1
+fi
+
+extract_version() {
+  local file_path="$1"
+  awk -F'"' '/^[[:space:]]*version "/ { print $2; exit }' "${file_path}"
+}
+
+ensure_contains() {
+  local file_path="$1"
+  local expected_text="$2"
+  if ! grep -Fq "${expected_text}" "${file_path}"; then
+    echo "Validation failed: expected text not found in ${file_path}: ${expected_text}"
+    exit 1
+  fi
+}
+
+ensure_count_at_least() {
+  local file_path="$1"
+  local pattern="$2"
+  local minimum_count="$3"
+  local actual_count
+  if ! actual_count="$(grep -cE "${pattern}" "${file_path}")"; then
+    actual_count="0"
+  fi
+  if (( actual_count < minimum_count )); then
+    echo "Validation failed: ${file_path} has ${actual_count} matches for '${pattern}', expected at least ${minimum_count}"
+    exit 1
+  fi
+}
+
+formula_version="$(extract_version "${FORMULA_PATH}")"
+
+if [[ -z "${formula_version}" ]]; then
+  echo "Validation failed: could not read version from formula"
+  exit 1
+fi
+
+ensure_contains "${FORMULA_PATH}" "on_macos do"
+ensure_contains "${FORMULA_PATH}" "on_linux do"
+ensure_contains "${FORMULA_PATH}" "Hardware::CPU.intel?"
+ensure_contains "${FORMULA_PATH}" "Hardware::CPU.arm?"
+ensure_count_at_least "${FORMULA_PATH}" '^[[:space:]]*sha256 "' 4
+
+ensure_contains "${FORMULA_PATH}" "releases/download/v${formula_version}/grounds-cli_${formula_version}_darwin_amd64.tar.gz"
+ensure_contains "${FORMULA_PATH}" "releases/download/v${formula_version}/grounds-cli_${formula_version}_darwin_arm64.tar.gz"
+ensure_contains "${FORMULA_PATH}" "releases/download/v${formula_version}/grounds-cli_${formula_version}_linux_amd64.tar.gz"
+ensure_contains "${FORMULA_PATH}" "releases/download/v${formula_version}/grounds-cli_${formula_version}_linux_arm64.tar.gz"
+
+echo "Tap validation passed (version=${formula_version})"