docs(release): bake tock/sqlite caveats + Go floor into README and formula

1f82ec7892feef9014442e3b488f8c0ee26b9273
Kevin Kortum <kevinkortum@me.com> · 2026-07-08 07:50

parent 83b6097e

docs(release): bake tock/sqlite caveats + Go floor into README and formula

Add a Requirements section to the README and a caveats block to the
generated Homebrew formula: tock on PATH (tested v1.9.8), sqlite backend
strongly recommended (file backend can drop tags/notes on edit), sqlite3
CLI optional for autocomplete, Go >= 1.26 to build from source. Formula
test now asserts tt --version.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Pc56rzYZo9TjJgXN951Psk

2 files changed

README.md +18 −2

@@ -12,8 +12,24 @@ Once published to the tap:
 
     brew install humdrum/tap/tt
 
-Requires `tock` on PATH. `tt menu`'s full-screen actions (watch/list/analyze)
-hand the terminal over to tock.
+## Requirements
+
+- **`tock` on PATH.** `tt` owns no storage — every read and write shells out to
+  your installed [`tock`](https://github.com/dhth/tock). Tested against tock
+  **v1.9.8**; older versions may predate the `report --json` / `add -s/-e`
+  contract `tt` relies on.
+- **tock's sqlite backend is strongly recommended.** `tt` works on any backend
+  for reading and adding, but editing an entry is a remove-then-re-add, and on
+  the file/markdown backend tock's `report --json` can omit tags/notes — so an
+  edit could silently drop them. On sqlite the full row round-trips intact.
+- **`sqlite3` CLI (optional).** Used only to pull history for autocomplete when
+  the sqlite backend is active. Missing it just falls back to `tock last`;
+  nothing breaks.
+- **Building from source needs Go ≥ 1.26.** The Homebrew formula is a source
+  build and pulls the Go toolchain automatically.
+
+`tt menu`'s full-screen actions (watch/list/analyze) hand the terminal over to
+tock.
 
 ## Commands

scripts/brew-release.sh +16 −0

@@ -59,8 +59,24 @@   def install
     system "go", "build", *std_go_args(ldflags: "-s -w -X main.version=#{version}"), "${PKG}"
   end
 
+  def caveats
+    <<~EOS
+      tt drives the tock time tracker — install tock and put it on PATH:
+        https://github.com/dhth/tock
+      Tested against tock v1.9.8 (report --json / add -s/-e contract).
+
+      tock's sqlite backend is strongly recommended. On the file/markdown
+      backend, editing an entry (a remove-then-re-add) can silently drop
+      tags/notes because tock's report --json may omit them there.
+
+      For history autocomplete, install the sqlite3 CLI (optional):
+        brew install sqlite
+    EOS
+  end
+
   test do
     assert_path_exists bin/"${REPO}"
+    assert_match version.to_s, shell_output("#{bin}/${REPO} --version")
   end
 end
 EOF