V1 CLI ship polish

.github/workflows/release.yml

@@ -9,8 +9,15 @@ permissions:
   contents: write
   packages: write  # Required for Docker push to ghcr.io
   id-token: write  # Required for keyless cosign signing via OIDC
+  security-events: write  # Required for SARIF upload in security scan
+  pull-requests: read
 
 jobs:
+  security:
+    name: Security scan
+    uses: ./.github/workflows/security.yml
+    secrets: inherit
+
   test:
     name: Test before release
     runs-on: ubuntu-latest
@@ -39,12 +46,38 @@ jobs:
       - name: Configure git for private modules
         run: git config --global url."https://x-access-token:${{ steps.app-token.outputs.token }}@github.com/".insteadOf "https://github.com/"
 
+      - name: Install golangci-lint
+        uses: golangci/golangci-lint-action@v9
+        with:
+          version: v2.9.0
+          install-only: true
+
+      - name: Cache BATS
+        id: cache-bats
+        uses: actions/cache@v5
+        with:
+          path: /usr/local/libexec/bats-core
+          key: bats-1.11.0
+
+      - name: Install BATS
+        if: steps.cache-bats.outputs.cache-hit != 'true'
+        run: |
+          git clone --depth 1 --branch v1.11.0 https://github.com/bats-core/bats-core.git /tmp/bats-core
+          sudo /tmp/bats-core/install.sh /usr/local
+
       - name: Run release quality gate
-        run: make fmt-check vet test provenance-check check-naming
+        run: |
+          make fmt-check vet lint test test-e2e provenance-check check-naming
+          go test -race -count=1 ./...
+
+      - name: Run govulncheck
+        run: |
+          go install golang.org/x/vuln/cmd/govulncheck@latest
+          govulncheck ./...
 
   release:
     name: Release
-    needs: test
+    needs: [test, security]
     runs-on: ubuntu-latest
     env:
       GOPRIVATE: github.com/basecamp/basecamp-sdk

.github/workflows/security.yml

@@ -8,6 +8,7 @@ on:
   schedule:
     # Weekly scan on Monday at 6am UTC
     - cron: '0 6 * * 1'
+  workflow_call:  # Allow release.yml to invoke the full security suite
   workflow_dispatch:
 
 permissions:
@@ -84,9 +85,9 @@ jobs:
         run: git config --global url."https://x-access-token:${{ steps.app-token.outputs.token }}@github.com/".insteadOf "https://github.com/"
 
       - name: Run gosec
-        uses: securego/gosec@v2.23.0
-        with:
-          args: '-no-fail -fmt sarif -out gosec-results.sarif ./...'
+        run: |
+          go install github.com/securego/gosec/v2/cmd/gosec@v2.23.0
+          gosec -no-fail -fmt sarif -out gosec-results.sarif ./...
 
       - name: Upload gosec scan results to GitHub Security tab
         uses: github/codeql-action/upload-sarif@v4
@@ -97,5 +98,11 @@ jobs:
 
   # NOTE: govulncheck runs in test.yml - not duplicated here
 
-  # TODO: Restore dependency-review job when repo goes public
-  # Requires GitHub Advanced Security, noisy during private dev
+  dependency-review:
+    name: Dependency Review
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    continue-on-error: true  # Requires GitHub Advanced Security (not available on all plans)
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/dependency-review-action@v4

.github/workflows/test.yml

@@ -259,7 +259,8 @@ jobs:
         run: |
           benchstat benchmarks-baseline.txt benchmarks.txt > comparison.txt 2>&1 || true
           if grep -E '\+[2-9][0-9]\.[0-9]+%|\+[1-9][0-9][0-9]+' comparison.txt; then
-            echo "::warning::Potential performance regression detected (>20% slower in some benchmarks)"
+            echo "::error::Performance regression detected (>20% slower). See benchmark comparison in step summary."
+            exit 1
           fi
 
       - name: Save benchmark baseline

.goreleaser.yaml

@@ -97,9 +97,9 @@ release:
     basecamp auth login
     ```
 
-    Requires `gh` CLI with access to the basecamp org. Other platforms: grab the matching archive from the assets below.
+    Other platforms: download the matching archive from the assets below.
 
-# Homebrew cask — deferred until repo goes public or cask auth for private repos is solved
+# Homebrew cask — deferred until cask tap is set up
 # homebrew_casks:
 #   - name: basecamp
 #     repository:
@@ -113,7 +113,7 @@ release:
 #       - basecamp
 #     skip_upload: auto
 
-# Scoop (Windows) — deferred, no internal Windows users
+# Scoop (Windows) — deferred, no Windows users yet
 # scoops:
 #   - name: basecamp
 #     repository:

Makefile

@@ -210,9 +210,18 @@ fmt-check:
 	@test -z "$$($(GOFMT) -s -l . | tee /dev/stderr)" || (echo "Code is not formatted. Run 'make fmt'" && exit 1)
 
 # Run linter (requires golangci-lint)
+# Prefer GOBIN/GOPATH binary (matches active Go toolchain) over PATH (may be Homebrew/system)
+GOLANGCI_LINT := $(shell go env GOBIN)/golangci-lint
+ifeq ($(wildcard $(GOLANGCI_LINT)),)
+  GOLANGCI_LINT := $(shell go env GOPATH)/bin/golangci-lint
+endif
+ifeq ($(wildcard $(GOLANGCI_LINT)),)
+  GOLANGCI_LINT := $(shell command -v golangci-lint 2>/dev/null)
+endif
+
 .PHONY: lint
 lint:
-	golangci-lint run ./...
+	$(GOLANGCI_LINT) run ./...
 
 # Tidy dependencies
 .PHONY: tidy

README.md

@@ -1,7 +1,5 @@
 # <img src="assets/basecamp-badge.svg" height="28" alt="Basecamp"> Basecamp CLI
 
-> **Prerelease.** This is an early internal release for 37signals dogfooding. The repo is private — all install methods below require GitHub access. Expect rough edges; file issues as you find them.
-
 `basecamp` is the official command-line interface for Basecamp. Manage projects, todos, messages, and more from your terminal or through AI agents.
 
 - Works standalone or with any AI agent (Claude, Codex, Copilot, Gemini)
@@ -20,7 +18,7 @@ That's it. You now have full access to Basecamp from your terminal.
 <details>
 <summary>Other installation methods</summary>
 
-**Go install** (requires `GOPRIVATE=github.com/basecamp/*`):
+**Go install:**
 ```bash
 go install github.com/basecamp/basecamp-cli/cmd/basecamp@latest
 ```
@@ -30,11 +28,6 @@ go install github.com/basecamp/basecamp-cli/cmd/basecamp@latest
 curl -fsSL https://raw.githubusercontent.com/basecamp/basecamp-cli/main/scripts/install.sh | bash
 ```
 
-**Windows (Scoop):**
-```bash
-scoop bucket add basecamp https://github.com/basecamp/homebrew-tap
-scoop install basecamp
-```
 </details>
 
 ## Usage
@@ -77,8 +70,8 @@ Breadcrumbs suggest next commands, making it easy for humans and agents to navig
 OAuth 2.1 with automatic token refresh. First login opens your browser:
 
 ```bash
-basecamp auth login              # Full read/write access
-basecamp auth login --scope read # Read-only access
+basecamp auth login              # Read-only access (default)
+basecamp auth login --scope full # Full read/write access
 basecamp auth token              # Print token for scripts
 ```
 
@@ -120,7 +113,7 @@ See [install.md](install.md) for step-by-step setup instructions.
 
 ```bash
 basecamp doctor              # Check CLI health and diagnose issues
-basecamp doctor -V           # Verbose output with details
+basecamp doctor --verbose    # Verbose output with details
 ```
 
 ## Development

go.mod

@@ -10,6 +10,7 @@ require (
 	github.com/charmbracelet/huh v0.8.0
 	github.com/charmbracelet/lipgloss v1.1.1-0.20250404203927-76690c660834
 	github.com/charmbracelet/x/term v0.2.1
+	github.com/fsnotify/fsnotify v1.8.0
 	github.com/gofrs/flock v0.13.0
 	github.com/mattn/go-runewidth v0.0.16
 	github.com/spf13/cobra v1.10.2

go.sum

@@ -71,6 +71,8 @@ github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkp
 github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f h1:Y/CXytFA4m6baUTXGLOoWe4PQhGxaX0KpnayAqC48p4=
 github.com/erikgeiser/coninput v0.0.0-20211004153227-1c3628e74d0f/go.mod h1:vw97MGsxSvLiUE2X8qFplwetxpGLQrlU1Q9AUEIzCaM=
+github.com/fsnotify/fsnotify v1.8.0 h1:dAwr6QBTBZIkG8roQaJjGof0pp0EeF+tNV7YBP3F/8M=
+github.com/fsnotify/fsnotify v1.8.0/go.mod h1:8jBTzvmWwFyi3Pb8djgCCO5IBqzKJ/Jwo8TRcHyHii0=
 github.com/godbus/dbus/v5 v5.1.0 h1:4KLkAxT3aOY8Li4FRJe/KvhoNFFxo0m6fNuFUO8QJUk=
 github.com/godbus/dbus/v5 v5.1.0/go.mod h1:xhWf0FNVPg57R7Z0UbKHbJfkEywrmjJnf7w5xrFpKfA=
 github.com/gofrs/flock v0.13.0 h1:95JolYOvGMqeH31+FC7D2+uULf6mG61mEZ/A8dRYMzw=

install.md

@@ -66,7 +66,7 @@ Opens browser for OAuth. Grant access when prompted.
 **Verify:**
 ```bash
 basecamp auth status
-# Expected: Authenticated as your@email.com
+# Expected: Authenticated (scope: read)
 ```
 
 ---

internal/appctx/context.go

@@ -64,6 +64,8 @@ type GlobalFlags struct {
 	Verbose  int // 0=off, 1=operations, 2=operations+requests (stacks with -v -v or -vv)
 	Stats    bool
 	NoStats  bool // Explicit disable (overrides --stats and dev default)
+	Hints    bool
+	NoHints  bool // Explicit disable (overrides --hints and dev default)
 	CacheDir string
 }
 
@@ -211,6 +213,9 @@ func (a *App) OK(data any, opts ...output.ResponseOption) error {
 		stats := a.Collector.Summary()
 		opts = append(opts, output.WithStats(&stats))
 	}
+	if !a.Flags.Hints || a.Flags.NoHints {
+		opts = append(opts, output.WithoutBreadcrumbs())
+	}
 	return a.Output.OK(data, opts...)
 }
 
@@ -297,7 +302,7 @@ func (a *App) printStatsToStderr(stats *observability.SessionMetrics) {
 
 	parts := stats.FormatParts()
 	if len(parts) > 0 {
-		fmt.Fprintf(os.Stderr, "\nStats: %s\n", strings.Join(parts, " | "))
+		fmt.Fprintf(os.Stderr, "\n%s\n", strings.Join(parts, " · "))
 	}
 }
 

internal/cli/root.go

@@ -72,6 +72,9 @@ func NewRootCmd() *cobra.Command {
 				}
 			}
 
+			// Resolve behavior preferences: explicit flag > config > version.IsDev()
+			resolvePreferences(cmd, cfg, &flags)
+
 			// Create app and store in context
 			app := appctx.NewApp(cfg)
 			app.Flags = flags
@@ -104,9 +107,12 @@ func NewRootCmd() *cobra.Command {
 
 	// Behavior flags
 	cmd.PersistentFlags().CountVarP(&flags.Verbose, "verbose", "v", "Verbose output (-v for ops, -vv for requests)")
-	cmd.PersistentFlags().BoolVar(&flags.Stats, "stats", version.IsDev(), "Show session statistics (default: on in dev builds)")
+	cmd.PersistentFlags().BoolVar(&flags.Stats, "stats", false, "Show session statistics (persisted via: basecamp config set stats true)")
 	cmd.PersistentFlags().BoolVar(&flags.NoStats, "no-stats", false, "Disable session statistics")
 	cmd.MarkFlagsMutuallyExclusive("stats", "no-stats")
+	cmd.PersistentFlags().BoolVar(&flags.Hints, "hints", false, "Show follow-up hints (persisted via: basecamp config set hints true)")
+	cmd.PersistentFlags().BoolVar(&flags.NoHints, "no-hints", false, "Disable follow-up hints")
+	cmd.MarkFlagsMutuallyExclusive("hints", "no-hints")
 	cmd.PersistentFlags().StringVar(&flags.CacheDir, "cache-dir", "", "Cache directory")
 
 	// Register tab completion for flags.
@@ -177,6 +183,7 @@ func Execute() {
 	cmd.AddCommand(commands.NewCompletionCmd())
 	cmd.AddCommand(commands.NewSetupCmd())
 	cmd.AddCommand(commands.NewDoctorCmd())
+	cmd.AddCommand(commands.NewUpgradeCmd())
 	cmd.AddCommand(commands.NewMigrateCmd())
 	cmd.AddCommand(commands.NewProfileCmd())
 	cmd.AddCommand(commands.NewTUICmd())
@@ -417,3 +424,32 @@ func transformCobraError(err error) error {
 
 	return err
 }
+
+// resolvePreferences resolves behavior flag values using the precedence chain:
+// explicit flag > config > version.IsDev()
+//
+// Flags register with default=false so we can detect explicit usage via Changed().
+// When no flag is passed, we check config, then fall back to version.IsDev().
+func resolvePreferences(cmd *cobra.Command, cfg *config.Config, flags *appctx.GlobalFlags) {
+	pf := cmd.PersistentFlags()
+
+	if !pf.Changed("stats") && (!pf.Changed("no-stats") || !flags.NoStats) {
+		if cfg.Stats != nil {
+			flags.Stats = *cfg.Stats
+		} else {
+			flags.Stats = version.IsDev()
+		}
+	}
+
+	if !pf.Changed("hints") && (!pf.Changed("no-hints") || !flags.NoHints) {
+		if cfg.Hints != nil {
+			flags.Hints = *cfg.Hints
+		} else {
+			flags.Hints = version.IsDev()
+		}
+	}
+
+	if !pf.Changed("verbose") && cfg.Verbose != nil {
+		flags.Verbose = *cfg.Verbose
+	}
+}