feat: add automatic update check notification for binary users

.claude/skills/release/SKILL.md

@@ -186,12 +186,22 @@ git pull origin main
 git push origin dev
 ```
 
+> **Important**: This sync ensures dev has the merge commit from main. Without it,
+> dev and main diverge. The CI `update-homebrew` job only pushes the formula
+> commit to dev — it does not bring the PR merge commit onto dev. This manual
+> `git pull origin main` is what ensures dev has the merge commit.
+
 The GitHub Release is distinct from the git tag — without it, the release won't appear on the repository's Releases page. Always create it.
 
 If the user merges the PR themselves and comes back, still offer to tag, release, and sync.
 
 ### Step 10: Wait for Release Workflow and Update Homebrew Formula
 
+> **Note**: The `update-homebrew` CI job in `.github/workflows/release.yml` runs automatically
+> after the release job and handles the formula update + push to dev (part of Step 10).
+> Step 11 (tap sync to `coleam00/homebrew-archon`) is always manual. Check the Actions tab
+> before running Step 10 manually.
+
 After the tag is pushed, `.github/workflows/release.yml` builds platform binaries and uploads them to the GitHub release. This takes 5-10 minutes. The Homebrew formula SHA256 values cannot be known until these binaries exist.
 
 **Wait for all assets to appear on the release:**
@@ -200,16 +210,16 @@ After the tag is pushed, `.github/workflows/release.yml` builds platform binarie
 echo "Waiting for release workflow to finish uploading binaries..."
 for i in {1..30}; do
   ASSET_COUNT=$(gh release view "vx.y.z" --repo coleam00/Archon --json assets --jq '.assets | length')
-  # Expect 6 assets: 5 binaries (darwin-arm64, darwin-x64, linux-arm64, linux-x64, windows-x64.exe) + checksums.txt
-  if [ "$ASSET_COUNT" -ge 6 ]; then
+  # Expect 7 assets: 5 binaries (darwin-arm64, darwin-x64, linux-arm64, linux-x64, windows-x64.exe) + archon-web.tar.gz + checksums.txt
+  if [ "$ASSET_COUNT" -ge 7 ]; then
     echo "All $ASSET_COUNT assets uploaded"
     break
   fi
-  echo "  Assets so far: $ASSET_COUNT/6 — waiting 30s (attempt $i/30)..."
+  echo "  Assets so far: $ASSET_COUNT/7 — waiting 30s (attempt $i/30)..."
   sleep 30
 done
 
-if [ "$ASSET_COUNT" -lt 6 ]; then
+if [ "$ASSET_COUNT" -lt 7 ]; then
   echo "ERROR: Release workflow did not finish uploading assets after 15 minutes"
   echo "Check https://github.com/coleam00/Archon/actions for the release workflow run"
   exit 1

CLAUDE.md

@@ -536,6 +536,7 @@ curl http://localhost:3637/api/conversations/<conversationId>/messages
 │   │   └── uploads/{convId}/     # Web UI file uploads (ephemeral)
 │   └── logs/                     # Workflow execution logs
 ├── web-dist/<version>/            # Cached web UI dist (archon serve, binary only)
+├── update-check.json              # Update check cache (binary builds, 24h TTL)
 ├── archon.db                     # SQLite database (when DATABASE_URL not set)
 └── config.yaml                   # Global configuration (non-secrets)
 ```
@@ -766,6 +767,9 @@ Pattern: Use `classifyIsolationError()` (from `@archon/isolation`) to map git er
 **Command Listing:**
 - `GET /api/commands` - List available command names (bundled + project-defined); optional `?cwd=`; returns `{ commands: [{ name, source: 'bundled' | 'project' }] }`
 
+**System:**
+- `GET /api/update-check` - Check for available updates; returns `{ updateAvailable, currentVersion, latestVersion, releaseUrl }`; skips GitHub API call for non-binary builds
+
 **OpenAPI Spec:**
 - `GET /api/openapi.json` - Generated OpenAPI 3.0 spec for all Zod-validated routes
 

packages/cli/src/cli.ts

@@ -80,7 +80,13 @@ import { setupCommand } from './commands/setup';
 import { validateWorkflowsCommand, validateCommandsCommand } from './commands/validate';
 import { serveCommand } from './commands/serve';
 import { closeDatabase } from '@archon/core';
-import { setLogLevel, createLogger } from '@archon/paths';
+import {
+  setLogLevel,
+  createLogger,
+  checkForUpdate,
+  BUNDLED_IS_BINARY,
+  BUNDLED_VERSION,
+} from '@archon/paths';
 import * as git from '@archon/git';
 
 /** Lazy-initialized logger (deferred so test mocks can intercept createLogger) */
@@ -159,6 +165,20 @@ async function closeDb(): Promise<void> {
   }
 }
 
+async function printUpdateNotice(quiet: boolean | undefined): Promise<void> {
+  if (quiet || !BUNDLED_IS_BINARY) return;
+  try {
+    const result = await checkForUpdate(BUNDLED_VERSION);
+    if (result?.updateAvailable) {
+      process.stderr.write(
+        `Update available: v${result.currentVersion} → v${result.latestVersion} — ${result.releaseUrl}\n`
+      );
+    }
+  } catch (err) {
+    getLog().debug({ err }, 'update_check.notice_failed');
+  }
+}
+
 /**
  * Main CLI entry point
  * Returns exit code (0 = success, non-zero = failure)
@@ -556,6 +576,7 @@ async function main(): Promise<number> {
         printUsage();
         return 1;
     }
+    await printUpdateNotice(values.quiet as boolean | undefined);
     return 0;
   } catch (error) {
     const err = error as Error;

packages/docs-web/src/content/docs/reference/api.md

@@ -352,6 +352,16 @@ curl -X PATCH http://localhost:3090/api/config/assistants \
 
 ---
 
+## System
+
+| Method | Path | Description |
+|--------|------|-------------|
+| GET | `/api/update-check` | Check for available updates (binary builds only) |
+
+Returns `{ updateAvailable, currentVersion, latestVersion, releaseUrl }`. For non-binary (source) builds, always returns `updateAvailable: false` without making external requests.
+
+---
+
 ## SSE Streaming
 
 | Path | Description |

packages/docs-web/src/content/docs/reference/archon-directories.md

@@ -32,6 +32,7 @@ Archon provides a unified directory and configuration system with:
 │           └── worktrees/    # Git worktrees for this project
 ├── worktrees/                # Legacy global worktrees (for repos not in workspaces/)
 ├── web-dist/<version>/       # Cached web UI dist (archon serve, binary only)
+├── update-check.json         # Update check cache (binary builds only, 24h TTL)
 └── config.yaml               # Global user configuration
 ```
 

packages/paths/src/index.ts

@@ -34,3 +34,12 @@ export type { Logger } from './logger';
 
 // Build-time constants (rewritten by scripts/build-binaries.sh)
 export { BUNDLED_IS_BINARY, BUNDLED_VERSION, BUNDLED_GIT_COMMIT } from './bundled-build';
+
+// Update check
+export {
+  checkForUpdate,
+  getCachedUpdateCheck,
+  isNewerVersion,
+  parseLatestRelease,
+} from './update-check';
+export type { UpdateCheckResult } from './update-check';