feat: home/root guard, size warning, offline fallback, cache TTL, self-update, enhanced status, exclude_patterns

- Home/root guard: refuse to analyze / watch from ~ or / (issue #115)
- Upload size warning: warn when archive exceeds 50 MB with hint to use .supermodel.json
- Graceful offline fallback: serve stale cached graph when API is unreachable
- Cache TTL: 30-day expiry on Get(); new Prune(maxAge), Stats(), NewestEntry() helpers
- .supermodel.json exclude_patterns: glob patterns for full path exclusions (e.g. "**/testdata/**")
- Enhanced status: shows cache size in bytes, last analysis timestamp
- Self-update: `supermodel update` downloads and installs the latest GitHub release;
  `supermodel update --check` prints available version without installing

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: greynewell

cmd/update.go

@@ -0,0 +1,59 @@
+package cmd
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/cobra"
+
+	"github.com/supermodeltools/cli/internal/build"
+	"github.com/supermodeltools/cli/internal/update"
+)
+
+func init() {
+	var checkOnly bool
+
+	c := &cobra.Command{
+		Use:   "update",
+		Short: "Update supermodel to the latest release",
+		Long: `Checks for a newer release on GitHub and, if found, downloads and installs it.
+
+Use --check to only print the latest available version without installing.`,
+		SilenceUsage: true,
+		RunE: func(cmd *cobra.Command, args []string) error {
+			if checkOnly {
+				latest, err := update.Check()
+				if err != nil {
+					return fmt.Errorf("check for updates: %w", err)
+				}
+				current := strings.TrimPrefix(build.Version, "v")
+				latestClean := strings.TrimPrefix(latest, "v")
+				if current == latestClean {
+					fmt.Printf("supermodel %s is up to date\n", build.Version)
+				} else {
+					fmt.Printf("current: %s  →  latest: %s\n", build.Version, latest)
+					fmt.Println("Run `supermodel update` to install.")
+				}
+				return nil
+			}
+
+			fmt.Println("Checking for updates…")
+			updated, err := update.Run()
+			if err != nil {
+				return err
+			}
+			if updated {
+				fmt.Printf("Updated to the latest version. Run `supermodel version` to confirm.\n")
+			} else {
+				fmt.Printf("supermodel %s is already up to date.\n", build.Version)
+			}
+			return nil
+		},
+	}
+
+	c.Flags().BoolVar(&checkOnly, "check", false, "check for updates without installing")
+	rootCmd.AddCommand(c)
+
+	// Allow `update` to run without an API key (it's independent of auth)
+	noConfigCommands["update"] = true
+}

internal/analyze/handler.go

@@ -37,6 +37,10 @@ func Run(ctx context.Context, cfg *config.Config, dir string, opts Options) erro
 // Uses git-based fingerprinting (~1ms for clean repos) to check the cache
 // before creating a zip. Only creates and uploads the zip on cache miss.
 func GetGraph(ctx context.Context, cfg *config.Config, dir string, force bool) (*api.Graph, string, error) {
+	if err := guardDir(dir); err != nil {
+		return nil, "", err
+	}
+
 	// Fast path: check cache using git fingerprint before creating zip.
 	if !force {
 		fingerprint, err := cache.RepoFingerprint(dir)
@@ -58,6 +62,13 @@ func GetGraph(ctx context.Context, cfg *config.Config, dir string, force bool) (
 	}
 	defer os.Remove(zipPath)
 
+	if info, statErr := os.Stat(zipPath); statErr == nil {
+		sizeMB := float64(info.Size()) / (1 << 20)
+		if sizeMB > 50 {
+			ui.Warn("Archive is %.0f MB — add patterns to .supermodel.json to reduce upload size", sizeMB)
+		}
+	}
+
 	hash, err := cache.HashFile(zipPath)
 	if err != nil {
 		return nil, "", err
@@ -76,6 +87,18 @@ func GetGraph(ctx context.Context, cfg *config.Config, dir string, force bool) (
 	ir, err := client.AnalyzeShards(ctx, zipPath, "analyze-"+hash[:16], nil)
 	spin.Stop()
 	if err != nil {
+		// Network/API failure — serve stale cache if available rather than hard-failing.
+		if stale, _ := cache.Get(hash); stale != nil {
+			ui.Warn("API unavailable (%v) — using stale cached result", err)
+			return stale, hash, nil
+		}
+		if fp, fpErr := cache.RepoFingerprint(dir); fpErr == nil {
+			fpKey := cache.AnalysisKey(fp, "graph", build.Version)
+			if stale, _ := cache.Get(fpKey); stale != nil {
+				ui.Warn("API unavailable (%v) — using stale cached result", err)
+				return stale, fpKey, nil
+			}
+		}
 		return nil, hash, err
 	}
 

internal/analyze/zip.go

@@ -38,6 +38,25 @@ var skipDirs = map[string]bool{
 	"venv":             true,
 }
 
+// guardDir returns an error if dir is the filesystem root or the user's home
+// directory — running analysis there would upload far too much.
+func guardDir(dir string) error {
+	abs, err := filepath.Abs(dir)
+	if err != nil {
+		return err
+	}
+	// Reject root (Unix "/" or Windows "C:\")
+	vol := filepath.VolumeName(abs)
+	if abs == vol+string(filepath.Separator) || abs == string(filepath.Separator) {
+		return fmt.Errorf("refusing to run in root directory — specify a project directory")
+	}
+	home, _ := os.UserHomeDir()
+	if home != "" && abs == home {
+		return fmt.Errorf("refusing to run in home directory (%s) — specify a project directory with --dir", abs)
+	}
+	return nil
+}
+
 // createZip archives the repository at dir into a temporary ZIP file and
 // returns its path. The caller is responsible for removing the file.
 //

internal/cache/cache.go

@@ -24,7 +24,10 @@ func dir() string {
 	return filepath.Join(config.Dir(), "cache")
 }
 
-// Get loads a cached graph for hash. Returns (nil, nil) on cache miss.
+// DefaultTTL is how long cached entries are considered fresh.
+const DefaultTTL = 30 * 24 * time.Hour
+
+// Get loads a cached graph for hash. Returns (nil, nil) on cache miss or expiry.
 func Get(hash string) (*api.Graph, error) {
 	data, err := os.ReadFile(filepath.Join(dir(), hash+".json"))
 	if os.IsNotExist(err) {
@@ -37,9 +40,83 @@ func Get(hash string) (*api.Graph, error) {
 	if err := json.Unmarshal(data, &e); err != nil {
 		return nil, fmt.Errorf("parse cache: %w", err)
 	}
+	if !e.CachedAt.IsZero() && time.Since(e.CachedAt) > DefaultTTL {
+		_ = Evict(hash) // stale — evict silently
+		return nil, nil
+	}
 	return e.Graph, nil
 }
 
+// Prune removes cache entries older than maxAge. Returns the number removed.
+func Prune(maxAge time.Duration) (int, error) {
+	entries, err := os.ReadDir(dir())
+	if os.IsNotExist(err) {
+		return 0, nil
+	}
+	if err != nil {
+		return 0, fmt.Errorf("read cache dir: %w", err)
+	}
+	removed := 0
+	for _, e := range entries {
+		if e.IsDir() || filepath.Ext(e.Name()) != ".json" {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		if time.Since(info.ModTime()) > maxAge {
+			if rmErr := os.Remove(filepath.Join(dir(), e.Name())); rmErr == nil {
+				removed++
+			}
+		}
+	}
+	return removed, nil
+}
+
+// Stats returns aggregate cache metrics: entry count and total size in bytes.
+func Stats() (count int, sizeBytes int64) {
+	entries, err := os.ReadDir(dir())
+	if err != nil {
+		return 0, 0
+	}
+	for _, e := range entries {
+		if e.IsDir() || filepath.Ext(e.Name()) != ".json" {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		count++
+		sizeBytes += info.Size()
+	}
+	return count, sizeBytes
+}
+
+// NewestEntry returns the modification time of the most recently written cache
+// entry, or the zero time if the cache is empty.
+func NewestEntry() time.Time {
+	entries, err := os.ReadDir(dir())
+	if err != nil {
+		return time.Time{}
+	}
+	var newest time.Time
+	for _, e := range entries {
+		if e.IsDir() || filepath.Ext(e.Name()) != ".json" {
+			continue
+		}
+		info, err := e.Info()
+		if err != nil {
+			continue
+		}
+		if info.ModTime().After(newest) {
+			newest = info.ModTime()
+		}
+	}
+	return newest
+}
+
 // Put stores g in the cache under hash.
 func Put(hash string, g *api.Graph) error {
 	if err := os.MkdirAll(dir(), 0o700); err != nil {

internal/shards/handler.go

@@ -56,12 +56,33 @@ type RenderOptions struct {
 	ThreeFile bool
 }
 
+// guardDir returns an error if dir is the filesystem root or the user's home
+// directory — running analysis there would upload far too much.
+func guardDir(dir string) error {
+	abs, err := filepath.Abs(dir)
+	if err != nil {
+		return err
+	}
+	vol := filepath.VolumeName(abs)
+	if abs == vol+string(filepath.Separator) || abs == string(filepath.Separator) {
+		return fmt.Errorf("refusing to run in root directory — specify a project directory with --dir")
+	}
+	home, _ := os.UserHomeDir()
+	if home != "" && abs == home {
+		return fmt.Errorf("refusing to run in home directory (%s) — specify a project directory with --dir", abs)
+	}
+	return nil
+}
+
 // Generate uploads a zip, builds the graph cache, and renders all shards.
 func Generate(ctx context.Context, cfg *config.Config, dir string, opts GenerateOptions) error {
 	repoDir, err := filepath.Abs(dir)
 	if err != nil {
 		return fmt.Errorf("resolving path: %w", err)
 	}
+	if err := guardDir(repoDir); err != nil {
+		return err
+	}
 
 	cacheFile := opts.CacheFile
 	if cacheFile == "" {
@@ -102,6 +123,13 @@ func Generate(ctx context.Context, cfg *config.Config, dir string, opts Generate
 	}
 	defer os.Remove(zipPath)
 
+	if info, statErr := os.Stat(zipPath); statErr == nil {
+		sizeMB := float64(info.Size()) / (1 << 20)
+		if sizeMB > 50 {
+			ui.Warn("Archive is %.0f MB — add exclude_dirs or exclude_patterns to .supermodel.json to reduce upload size", sizeMB)
+		}
+	}
+
 	// Read previous domains from cache for LLM seeding (stabilizes names across refreshes)
 	var prevDomains []api.PreviousDomain
 	if data, readErr := os.ReadFile(cacheFile); readErr == nil {
@@ -123,6 +151,22 @@ func Generate(ctx context.Context, cfg *config.Config, dir string, opts Generate
 	ir, err := client.AnalyzeShards(ctx, zipPath, "shards-"+idemKey[:8], prevDomains)
 	spin.Stop()
 	if err != nil {
+		// Network/API failure — fall back to stale cache and re-render rather than hard-failing.
+		if data, readErr := os.ReadFile(cacheFile); readErr == nil {
+			var staleIR api.ShardIR
+			if json.Unmarshal(data, &staleIR) == nil && len(staleIR.Graph.Nodes) > 0 {
+				ui.Warn("API unavailable (%v) — rendering from stale cache", err)
+				staleCache := NewCache()
+				staleCache.Build(&staleIR)
+				files := staleCache.SourceFiles()
+				written, renderErr := renderShards(repoDir, staleCache, files, opts.DryRun, opts.ThreeFile)
+				if renderErr != nil {
+					return fmt.Errorf("API error: %w; stale render also failed: %v", err, renderErr)
+				}
+				ui.Success("Wrote %d shards from stale cache (%d nodes)", written, len(staleIR.Graph.Nodes))
+				return nil
+			}
+		}
 		return err
 	}
 
@@ -166,6 +210,9 @@ func Watch(ctx context.Context, cfg *config.Config, dir string, opts WatchOption
 	if err != nil {
 		return fmt.Errorf("resolving path: %w", err)
 	}
+	if err := guardDir(repoDir); err != nil {
+		return err
+	}
 
 	cacheFile := opts.CacheFile
 	if cacheFile == "" {