fix: harden the tabex Homebrew formula

Formula/tabex.rb

@@ -62,24 +62,42 @@ def curl(*args, print_stdout: true, **options)
 class Tabex < Formula
   desc "Tabex CLI for browser session, capture, and page inspection"
   homepage "https://github.com/shpitdev/tabex"
-  version "0.0.3"
+  version "0.0.4"
   license :cannot_represent
   depends_on arch: :arm64
 
   on_macos do
     on_arm do
-      url "https://api.github.com/repos/shpitdev/tabex/releases/assets/400657957",
+      url "https://api.github.com/repos/shpitdev/tabex/releases/assets/401429381",
           using: TabexGitHubReleaseDownloadStrategy,
-          resolved_basename: "tabex_v0.0.3_darwin_arm64.tar.gz"
-      sha256 "7c72aa51434c55f6bffbaaa6606883f5a45efce4f57e04ef02eb65ed9533439c"
+          resolved_basename: "tabex_v0.0.4_darwin_arm64.tar.gz"
+      sha256 "8e5bdf30d9a57d34fec3bbb8973041dd1f8df821325652d1d16f40083f98b666"
     end
   end
 
   def install
     bin.install "tabex"
   end
 
+  def caveats
+    <<~EOS
+      Tabex needs browser-profile and extension setup after install.
+      Start with:
+        tabex setup
+
+      That saves browser config, installs or updates the managed Chrome extension locally,
+      and prints the Chrome load or refresh steps.
+    EOS
+  end
+
   test do
-    assert_match version.to_s, shell_output("#{bin}/tabex version")
+    require "json"
+
+    payload = JSON.parse(shell_output("#{bin}/tabex --json"))
+    assert_equal "tabex", payload["command"]
+    assert_equal "tabex <command>", payload["usage"]
+    assert_equal "v#{version}", payload["version"]
+    assert_equal "docs/curated-e2e-examples.md", payload["curatedExamplesDoc"]
+    assert_equal "setup", payload["examples"].first["label"]
   end
 end

README.md

@@ -33,6 +33,14 @@ HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install shpitdev/tap/tabex
 HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install shpitdev/tap/osyrra
 ```
 
+After `brew install shpitdev/tap/tabex`, start with:
+
+```bash
+tabex setup
+```
+
+That saves browser config, installs or updates the managed Chrome extension locally, and prints the Chrome load or refresh steps.
+
 ## Current Limitation
 
 - Both formulae are macOS arm64 only. The upstream releases do not ship a `darwin_amd64` asset today; add one upstream and the updater scripts can gain an `on_intel` block.

docs/setup.md

@@ -84,6 +84,14 @@ For local `brew install shpitdev/tap/tabex`, the formula uses the same auth path
 - if none are set, it falls back to `gh auth token`
 - in headless environments, prefer `HOMEBREW_GITHUB_API_TOKEN="$(gh auth token)" brew install ...`
 
+For `tabex`, the formula caveat currently points users at:
+
+```bash
+tabex setup
+```
+
+That is intentional. `v0.0.4` is the first stable release that ships the source-repo-side `setup` flow, so the tap can now safely point users at the real first-run path instead of a generic help screen.
+
 ## Package-Manager Install Behavior
 
 Both private formulae use install-side GitHub auth:

scripts/update-tabex.sh

@@ -181,8 +181,26 @@ class Tabex < Formula
     bin.install "tabex"
   end
 
+  def caveats
+    <<~EOS
+      Tabex needs browser-profile and extension setup after install.
+      Start with:
+        tabex setup
+
+      That saves browser config, installs or updates the managed Chrome extension locally,
+      and prints the Chrome load or refresh steps.
+    EOS
+  end
+
   test do
-    assert_match version.to_s, shell_output("#{bin}/tabex version")
+    require "json"
+
+    payload = JSON.parse(shell_output("#{bin}/tabex --json"))
+    assert_equal "tabex", payload["command"]
+    assert_equal "tabex <command>", payload["usage"]
+    assert_equal "v#{version}", payload["version"]
+    assert_equal "docs/curated-e2e-examples.md", payload["curatedExamplesDoc"]
+    assert_equal "setup", payload["examples"].first["label"]
   end
 end
 EOF

scripts/validate-formulae.sh

@@ -13,6 +13,10 @@ if [[ -f "${tabex_formula}" ]]; then
   grep -q 'using: TabexGitHubReleaseDownloadStrategy' "${tabex_formula}"
   grep -q 'resolved_basename: "tabex_v' "${tabex_formula}"
   grep -q 'url "https://api.github.com/repos/shpitdev/tabex/releases/assets/' "${tabex_formula}"
+  grep -q 'shell_output("#{bin}/tabex --json")' "${tabex_formula}"
+  grep -q 'assert_equal "v#{version}", payload\["version"\]' "${tabex_formula}"
+  grep -q 'Tabex needs browser-profile and extension setup after install.' "${tabex_formula}"
+  grep -q 'tabex setup' "${tabex_formula}"
 fi
 
 osyrra_formula="${repo_root}/Formula/osyrra.rb"