fix: install Pinecone CLI as a Homebrew cask (formula disabled 2026-03-30)

[mcdgavin]

Problem

The Pinecone CLI install instructions in the agent-facing docs no longer work. The pinecone-io/tap/pinecone formula was disabled on 2026-03-30 when the CLI migrated to a cask, so an assistant following these instructions produces:

Error: pinecone-io/tap/pinecone has been disabled because it has migrated to a
cask. Reinstall with: brew uninstall pinecone-io/tap/pinecone && brew install
--cask pinecone-io/tap/pinecone! It was disabled on 2026-03-30.

The upgrade advice brew update && brew upgrade pinecone breaks for the same reason: pinecone is now a cask token, and the formula it used to refer to is disabled.

Verified against the tap: Formula/pinecone.rb carries disable! date: "2026-03-30" pointing at the cask, and Casks/pinecone.rb is the live GoReleaser-generated cask (currently 1.0.1). pinecone-io/cli's README already documents the cask form.

Fix

Was	Now
brew tap pinecone-io/tap + brew install pinecone-io/tap/pinecone	brew install --cask pinecone-io/tap/pinecone
brew tap pinecone-io/tap && brew install pinecone-io/tap/pinecone	brew install --cask pinecone-io/tap/pinecone
brew update && brew upgrade pinecone	brew upgrade --cask pinecone-io/tap/pinecone

File: AGENTS.md (macOS install block and the pre-quickstart checklist). This file is a copy of _AGENTS-orig-python.md from pinecone-io/pinecone-agents-ref; the same change is submitted there.

Each macOS install block also gains one comment line telling the assistant to brew uninstall pinecone-io/tap/pinecone first if the CLI was installed before the migration, since Homebrew refuses to install the cask over the disabled formula. Kept to a single comment to stay token-cheap.

Why drop the separate brew tap step

• brew install taps automatically for a fully qualified user/repo/name.
• Since Homebrew 6.0.0, non-official taps require explicit trust. Installing a fully qualified cask trusts only that cask; the tap-then-short-name form now additionally needs brew trust. Homebrew's Tap Trust docs give brew install --cask user/repository/cask as the canonical form.

Verification

• Clean-state run on Homebrew 6.0.22, starting with the tap untapped, no trust entries, and no cask installed. brew install --cask pinecone-io/tap/pinecone alone tapped pinecone-io/tap, printed Trusted cask pinecone-io/tap/pinecone (item-level trust, not whole-tap), installed cask 1.0.1, and pc version prints 1.0.1. Exit 0. Note the tap still ships the disabled formula alongside the cask (Tapped 1 cask and 1 formula), which is why the old command produced the confusing "Treating ... as a formula" warning before failing.
• brew upgrade --cask pinecone-io/tap/pinecone on the fresh install reports the latest version is already installed.
• grep -rn "brew tap pinecone-io\|brew install pinecone-io/tap\|brew upgrade pinecone" over the repo returns nothing.

Related

Same fix across the org: pinecone-io/skills#33, pinecone-io/pinecone-claude-code-plugin#46, pinecone-io/pinecone-cursor-plugin#24, pinecone-io/gemini-cli-extension#22, pinecone-io/pinecone-codex-plugin#3.

---

Note

Low Risk
Documentation-only changes to Homebrew install commands; no application or runtime code is affected.

Overview
Updates agent-facing CLI install docs in AGENTS.md so macOS instructions match Homebrew after the Pinecone CLI moved from a formula to a cask (formula disabled 2026-03-30).

Install/upgrade now use brew install --cask pinecone-io/tap/pinecone and brew upgrade --cask pinecone-io/tap/pinecone, dropping the separate brew tap step and the broken brew upgrade pinecone path. A one-line comment tells agents to brew uninstall pinecone-io/tap/pinecone first if the old formula is still installed. The same cask commands appear in the Setup Prerequisites checklist for all quickstarts.

^{Reviewed by Cursor Bugbot for commit 1d29cae. Bugbot is set up for automated code reviews on this repo. Configure here.}