garrytan · garrytan · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026 · Mar 20, 2026
diff --git a/.gitignore b/.gitignore
@@ -18,9 +18,10 @@ extension/.auth.json
 .gstack-worktrees/
 /tmp/
 *.log
+supabase/.temp/
+bun.lock
 *.bun-build
 .env
 .env.local
 .env.*
 !.env.example
-supabase/.temp/
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -112,6 +112,7 @@ gstack/
 ├── extension/       # Chrome extension (side panel + activity feed + CSS inspector)
 ├── lib/             # Shared libraries (worktree.ts)
 ├── docs/designs/    # Design documents
+├── gstack-submit/   # /gstack-submit skill (showcase gallery submission)
 ├── setup-deploy/    # /setup-deploy skill (one-time deploy config)
 ├── .github/         # CI workflows + Docker image
 │   ├── workflows/   # evals.yml (E2E on Ubicloud), skill-docs.yml, actionlint.yml

diff --git a/PRIVACY.md b/PRIVACY.md
@@ -0,0 +1,180 @@
+# Privacy Policy
+
+**Last updated:** 2026-03-26
+
+gstack is an open-source CLI tool. This policy explains what data gstack collects, why, and how you control it.
+
+## The short version
+
+- **Telemetry is off by default.** Nothing is sent unless you say yes.
+- **We never collect your code, file paths, repo names, prompts, or any content you write.**
+- **You can change your mind anytime:** `gstack-config set telemetry off`
+- **Screenshots you upload are yours.** You can delete them anytime.
+
+---
+
+## 1. Telemetry
+
+### What we collect (if you opt in)
+
+gstack has four data tiers:
+
+| Tier | What's sent | Identifier |
+|------|------------|------------|
+| **Off** (default) | Nothing | None |
+| **Anonymous** | Skill name, duration, success/fail, gstack version, OS | None — no way to connect sessions |
+| **Community** | Same as anonymous | Random UUID (`~/.gstack/.install-id`) — connects sessions from one device |
+| **Logged in** | Same as community, plus screenshots tied to your account | Email address + GitHub username (via OAuth) |
+
+The first three tiers are chosen during first run. The **logged in** tier applies when you sign in to gstack.gg to use features like PR screenshots. Your email and GitHub username are associated with your uploaded screenshots and auth session. Logging in does not retroactively attach your identity to prior telemetry events.
+
+### What we never collect
+
+- Source code or file contents
+- File paths or directory structures
+- Repository names or branch names
+- Git commits, diffs, or history
+- Prompts, questions, or conversations
+- Usernames, hostnames, or IP addresses (not logged server-side)
+- Any content you write or generate
+
+### How it works
+
+1. Events are logged locally to `~/.gstack/analytics/skill-usage.jsonl`
+2. A background sync (`gstack-telemetry-sync`) sends unsent events to Supabase
+3. Local-only fields (`repo`, `_branch`, `_repo_slug`) are **stripped before sending**
+4. Sync is rate-limited to once per 5 minutes, batched (max 100 events)
+5. If sync fails, events stay local — nothing is lost or retried aggressively
+
+### Update checks
+
+gstack checks for updates by pinging our server with:
+- Your gstack version
+- Your OS (darwin/linux)
+- A random device UUID
+
+This happens regardless of telemetry tier because it's equivalent to what any package manager (Homebrew, npm) sends. No usage data is included. You can verify this in `bin/gstack-update-check`.
+
+---
+
+## 2. Screenshots (PR Screenshots feature)
+
+When you use the PR Screenshots feature during `/ship`:
+
+### What's stored
+
+- **Screenshot images** (PNGs) uploaded to a private Supabase Storage bucket
+- **Metadata:** nanoid, your user ID, slugified repo name, slugified branch name, viewport size, timestamp
+- Images are served through a proxy (`gstack.gg/i/{id}`) that adds a watermark — raw images are never publicly accessible
+
+### What's NOT stored
+
+- No source code or file contents
+- No git history or commit data
+- No prompt or conversation data
+
+### Your control
+
+- You can delete your screenshots anytime (authenticated DELETE to the API)
+- Orphan screenshots (no PR number after 24 hours) are automatically cleaned up
+- Images are tied to your gstack.gg account — you own them
+
+---
+
+## 3. Authentication
+
+gstack.gg supports two auth methods:
+
+- **GitHub OAuth** — we receive your GitHub username and email. We don't access your repos, code, or any GitHub data beyond basic profile.
+- **Email OTP** — we store your email address to send verification codes.
+
+Auth tokens are stored locally at `~/.gstack/auth-token.json` with file permissions `0600` (owner-only read/write). Tokens are standard Supabase JWT tokens and can be revoked by logging out (`gstack-auth logout`).
+
+---
+
+## 4. Data storage and security
+
+All data is stored in [Supabase](https://supabase.com) (open-source Firebase alternative):
+
+- **Row-Level Security (RLS)** on all tables — direct database access is denied even with the publishable API key
+- **Edge functions** validate schema, enforce event type allowlists, and limit field lengths
+- **The Supabase publishable key in our repo is a public key** (like a Firebase API key) — it cannot bypass RLS
+- **Screenshot storage bucket is private** — images are only accessible through the watermark proxy using a service-role key
+
+The full database schema is in [`supabase/migrations/`](supabase/migrations/) — you can verify exactly what's stored.
+
+---
+
+## 5. Showcase Submissions
+
+When you run `/gstack-submit`, gstack helps you compose a submission for the gstack.gg showcase gallery. This is **user-initiated and user-approved**, different from telemetry (which runs in the background).
+
+### What gets sent (only after you preview and approve)
+
+| Data | Source | You control it |
+|------|--------|---------------|
+| Project title, tagline, description | AI-generated, you edit before sending | Yes, edit or cancel |
+| Screenshot | Browse tool captures your deployed URL | Yes, you provide the URL |
+| Build stats (commit count, LOC, skills used) | Local git + analytics files | Yes, preview before sending |
+| Build story | AI-written from design docs + optionally transcripts | Yes, preview before sending |
+| Repo URL | Your git remote | Yes, can omit |
+
+### What never gets sent
+
+- Raw source code or file contents
+- Claude Code transcripts (read locally, never transmitted, only the AI-generated summary)
+- Private URLs or credentials found in local files
+
+### Transcript reading (opt-in)
+
+If you choose to let gstack read your Claude Code transcripts for a richer build story:
+- Transcripts are read **locally only**, never sent to any server
+- Only pattern-matched excerpts (decision moments, skill usage) are read, not full conversations
+- The AI writes a narrative summary; the raw transcript text is never included in the submission
+- You preview the full build story before it's sent anywhere
+
+---
+
+## 6. Data retention
+
+| Data type | Retention |
+|-----------|-----------|
+| Telemetry events | Indefinite (aggregated, no PII) |
+| Update check pings | Indefinite (version + OS only) |
+| Device codes (auth) | Deleted 15 minutes after expiry |
+| Orphan screenshots | Deleted 24 hours after upload if no PR is created |
+| Active screenshots | Retained until you delete them |
+
+---
+
+## 7. Your rights
+
+- **Access:** Run `gstack-analytics` to see all your local telemetry data. The JSONL file at `~/.gstack/analytics/skill-usage.jsonl` is plain text — you can read it directly.
+- **Opt out:** `gstack-config set telemetry off` — stops all collection and syncing instantly.
+- **Delete local data:** Remove `~/.gstack/analytics/` to clear all local telemetry.
+- **Delete screenshots:** Authenticated DELETE request to the upload API, or contact us.
+- **Delete account:** Contact us at the email below to deactivate your account. You will lose access to your data, including uploaded screenshots and account features. Previously collected telemetry and usage data may be retained and used by GStack, the GStack core team, or Y Combinator to improve the product.
+
+---
+
+## 8. Data ownership and use
+
+GStack is owned by Garry Tan via copyright. Telemetry data collected through GStack may be used by Garry Tan, the GStack core team, or Y Combinator to improve GStack. We will never sell your data.
+
+### Third-party services
+
+- **Supabase** hosts our database and storage (their privacy policy: https://supabase.com/privacy)
+- **Vercel** hosts gstack.gg (their privacy policy: https://vercel.com/legal/privacy-policy)
+- **GitHub** provides OAuth authentication
+
+---
+
+## 9. Changes
+
+We'll update this policy as gstack evolves. Material changes will be noted in the [CHANGELOG](CHANGELOG.md). The "Last updated" date at the top always reflects the current version.
+
+---
+
+## Contact
+
+Questions about privacy? Open an issue at https://github.com/garrytan/gstack/issues or email privacy@gstack.gg.
diff --git a/README.md b/README.md
@@ -42,11 +42,13 @@ Fork it. Improve it. Make it yours. And if you want to hate on free open source
 
 **Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Git](https://git-scm.com/), [Bun](https://bun.sh/) v1.0+, [Node.js](https://nodejs.org/) (Windows only)
 
-### Step 1: Install on your machine
+### One-liner install
 
-Open Claude Code and paste this. Claude does the rest.
+```bash
+bash <(curl -fsSL https://github.com/ghraw/garrytan/gstack/main/install.sh)
+```
 
-> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it.
+> Install gstack: run **`git clone --single-branch --depth 1 https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy, /canary, /benchmark, /browse, /connect-chrome, /qa, /qa-only, /design-review, /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex, /cso, /autoplan, /gstack-submit, /plan-devex-review, /devex-review, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn. Then ask the user if they also want to add gstack to the current project so teammates get it.
 
 ### Step 2: Team mode — auto-update for shared repos (recommended)
 
@@ -209,6 +211,7 @@ Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-
 | `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. `/retro global` runs across all your projects and AI tools (Claude Code, Codex, Gemini). |
 | `/browse` | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. `/open-gstack-browser` launches GStack Browser with sidebar, anti-bot stealth, and auto model routing. |
 | `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
+| `/gstack-submit` | **Community Showcase** | Submit your project to the gstack.gg gallery. Gathers build context (git stats, skills used), browses your deployed site, optionally reads Claude transcripts for the build story, writes a rich markdown entry, opens it in your browser for review, then submits. |
 | `/autoplan` | **Review Pipeline** | One command, fully reviewed plan. Runs CEO → design → eng review automatically with encoded decision principles. Surfaces only taste decisions for your approval. |
 | `/learn` | **Memory** | Manage what gstack learned across sessions. Review, search, prune, and export project-specific patterns, pitfalls, and preferences. Learnings compound across sessions so gstack gets smarter on your codebase over time. |
 
@@ -356,6 +359,7 @@ I open sourced how I build software. You can fork it and make it your own.
 | [Architecture](ARCHITECTURE.md) | Design decisions and system internals |
 | [Browser Reference](BROWSER.md) | Full command reference for `/browse` |
 | [Contributing](CONTRIBUTING.md) | Dev setup, testing, contributor mode, and dev mode |
+| [Privacy](PRIVACY.md) | Telemetry, screenshots, auth, showcase submissions, data retention |
 | [Changelog](CHANGELOG.md) | What's new in every version |
 
 ## Privacy & Telemetry
@@ -372,6 +376,8 @@ Data is stored in [Supabase](https://supabase.com) (open source Firebase alterna
 
 **Local analytics are always available.** Run `gstack-analytics` to see your personal usage dashboard from the local JSONL file — no remote data needed.
 
+**Full privacy policy:** [PRIVACY.md](PRIVACY.md) — covers telemetry, screenshots, auth, data retention, and your rights.
+
 ## Troubleshooting
 
 **Skill not showing up?** `cd ~/.claude/skills/gstack && ./setup`
@@ -397,7 +403,7 @@ Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-desig
 /design-consultation, /design-shotgun, /design-html, /review, /ship, /land-and-deploy,
 /canary, /benchmark, /browse, /open-gstack-browser, /qa, /qa-only, /design-review,
 /setup-browser-cookies, /setup-deploy, /retro, /investigate, /document-release, /codex,
-/cso, /autoplan, /pair-agent, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn.
+/cso, /autoplan, /gstack-submit, /pair-agent, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, /learn.
 ```
 
 ## License

diff --git a/TODOS.md b/TODOS.md
@@ -406,6 +406,20 @@ Linux cookie import shipped in v0.11.11.0 (Wave 3). Supports Chrome, Chromium, B
 **Priority:** P3
 **Depends on:** Browse sessions
 
+## Distribution
+
+### Homebrew tap
+
+**What:** Create a separate repo (`homebrew-gstack`) with a Homebrew formula so users can `brew tap garrytan/gstack && brew install gstack`.
+
+**Why:** Gold-standard dev tool distribution. Complements the curl-pipe-bash installer. Familiar install flow, automatic updates via `brew upgrade`, discoverable via Homebrew search.
+
+**Context:** The curl-pipe-bash installer (`install.sh`) ships first. The Homebrew formula would clone the repo + run `./setup`, similar to the installer. Needs a separate GitHub repo (`garrytan/homebrew-gstack`) with a `Formula/gstack.rb` file (~20 lines). Must be updated on each release.
+
+**Effort:** S (human: ~2h / CC: ~10 min)
+**Priority:** P2
+**Depends on:** install.sh shipping first
+
 ## Infrastructure
 
 ### /setup-gstack-upload skill (S3 bucket)