v1.0.0 release prep: docs rewrite, CI, dependabot, --version, SECURITY.md

Two prior commits' worth of v1.0.0 readiness work, squashed:

- README rewrite to production-grade layout (hero banner, badges, restructured Installation/Usage/Authentication/CI-CD)
- documentation/architecture.md refreshed for current packages, multi-browser support, S3 corrections; mermaid data-flow diagram
- LICENSE: extend copyright to 2025-2026
- .github/workflows/test.yml: PR-time CI (vet/test/build)
- .github/dependabot.yml: weekly gomod + github-actions updates
- main.go + .goreleaser.yml: --version flag wired through ldflags
- SECURITY.md: private vulnerability reporting policy
- README note: Chrome 127+ on Windows not yet supported (kooky upstream, tracking #4)
- Bumped actions/checkout and actions/setup-go to v6 (Node 24)

Author: drogers0

.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: gomod
+    directory: "/"
+    schedule:
+      interval: weekly
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly

.github/workflows/release.yml

@@ -13,12 +13,12 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Go
-        uses: actions/setup-go@v5
+        uses: actions/setup-go@v6
         with:
           go-version: stable
 

.github/workflows/test.yml

@@ -0,0 +1,18 @@
+name: Test
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-go@v6
+        with:
+          go-version: stable
+      - run: go vet ./...
+      - run: go test -race -cover ./...
+      - run: go build ./...

.goreleaser.yml

@@ -6,7 +6,7 @@ builds:
     env:
       - CGO_ENABLED=0
     ldflags:
-      - -s -w
+      - -s -w -X main.version={{.Version}}
     goos:
       - darwin
       - linux

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025 drogers0
+Copyright (c) 2025-2026 drogers0
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,201 +1,199 @@
-# gh-image
+<p align="center">
+  <img src="https://github.com/user-attachments/assets/92463e67-b897-4212-91b4-a4f9b80ec4d4" alt="gh-image banner" width="640">
+</p>
 
-![banner](https://github.com/user-attachments/assets/92463e67-b897-4212-91b4-a4f9b80ec4d4)
+<p align="center">
+  <em>Drop images into GitHub issues, PRs, and READMEs, straight from the command line.</em>
+</p>
 
-A `gh` CLI extension that uploads images to GitHub from the command line.
+<p align="center">
+  <a href="https://github.com/drogers0/gh-image/releases/latest"><img src="https://img.shields.io/github/v/release/drogers0/gh-image?color=blue" alt="Latest release"></a>
+  <a href="https://github.com/drogers0/gh-image/stargazers"><img src="https://img.shields.io/github/stars/drogers0/gh-image?style=flat&color=yellow" alt="GitHub stars"></a>
+  <a href="https://github.com/drogers0/gh-image/releases"><img src="https://img.shields.io/github/downloads/drogers0/gh-image/total?color=green" alt="Total downloads"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/drogers0/gh-image?color=lightgrey" alt="License: MIT"></a>
+  <a href="https://goreportcard.com/report/github.com/drogers0/gh-image"><img src="https://goreportcard.com/badge/github.com/drogers0/gh-image" alt="Go Report Card"></a>
+</p>
 
-GitHub has no public API for image uploads — the web UI uses an internal endpoint that produces URLs scoped to a repository's visibility. This tool replicates that flow, so images on private repos stay private.
+---
 
-## Usage
+GitHub has no public API for image uploads. The web UI uses an internal endpoint that produces `user-attachments` URLs whose visibility is scoped to the repository they were uploaded to. `gh-image` replicates that flow as a `gh` CLI extension, so you can drop a screenshot into a bug report, README, or Slack thread without leaving the terminal — and images on private repos stay private.
 
-```bash
-# Upload an image and get the markdown (infers repo from current git workspace)
-gh image screenshot.png
+```console
+$ gh image screenshot.png
+![screenshot.png](https://github.com/user-attachments/assets/88f4599a-…-bc24)
+```
 
-# Upload multiple images
-gh image img1.png img2.png
+## Installation
 
-# Explicit repo (when not in a git workspace or targeting a different repo)
-gh image screenshot.png --repo owner/repo
+```bash
+gh extension install drogers0/gh-image
 ```
 
-Output:
-```
-![screenshot](https://github.com/user-attachments/assets/<uuid>)
+That's it. The [`gh` CLI](https://cli.github.com) auto-detects your platform and downloads the prebuilt binary. Pre-built releases ship for **macOS** (arm64, amd64), **Linux** (amd64, arm64), and **Windows** (amd64).
+
+<details>
+<summary>Build from source</summary>
+
+```bash
+git clone https://github.com/drogers0/gh-image
+cd gh-image
+go build -o gh-image
+gh extension install .
 ```
 
-### Example: Upload an image and attach it to a GitHub issue
+Requires Go 1.26+.
+
+</details>
+
+## Usage
 
 ```bash
-# Upload the image
-gh image screenshot.png --repo owner/repo
-# Output: ![screenshot.png](https://github.com/user-attachments/assets/88f4599a-...)
+# Upload an image (infers repo from the current git workspace)
+gh image screenshot.png
 
-# Use the output in a new issue
-gh issue create --repo owner/repo \
-  --title "Bug report" \
-  --body "Here's what I see:
+# Upload multiple images at once
+gh image hero.png diagram.png chart.png
 
-![screenshot.png](https://github.com/user-attachments/assets/88f4599a-...)
-"
+# Target a specific repository
+gh image screenshot.png --repo owner/repo
 ```
 
-## Install
+Each successful upload prints a ready-to-paste markdown reference on its own line:
 
-```bash
-gh extension install drogers0/gh-image
+```
+![hero.png](https://github.com/user-attachments/assets/…)
+![diagram.png](https://github.com/user-attachments/assets/…)
 ```
 
-## How It Works
+If any upload fails, the error is printed to stderr and the process exits non-zero — other images in the batch still upload.
 
-1. Reads your GitHub session cookie from your browser's local cookie store (encrypted cookie decryption handled automatically)
-2. Uploads the image through GitHub's internal asset upload flow (the same one the web UI uses)
-3. Prints a markdown image reference to stdout
+### Pipe directly into an issue, PR, or comment
 
-The upload produces `https://github.com/user-attachments/assets/<uuid>` URLs — the same format as drag-and-drop uploads in the browser. Images inherit the repository's visibility: private repo images require authentication to view.
+From inside the repo's working directory, both `gh image` and `gh issue create` infer the target repository automatically:
 
-See [documentation/github-image-upload-flow.md](documentation/github-image-upload-flow.md) for the full reverse-engineered upload protocol.
+```bash
+gh issue create \
+  --title "Login button stuck in loading state" \
+  --body "Repro on staging:
+
+$(gh image bug.png)
+
+Happens consistently after the third click."
+```
 
 ## Authentication
 
-No tokens or OAuth setup required. The tool reads your `user_session` cookie directly from your browser's cookie database on disk. On macOS, a Keychain prompt may appear on first use to authorize access to the browser's encryption key.
+`gh-image` authenticates with your existing GitHub session — **no tokens to provision, no OAuth scopes to configure** for everyday local use. The tool reads the `user_session` cookie from your browser's encrypted cookie store.
 
-Supported browsers:
-- Chrome
-- Brave
-- Chromium
-- Edge
-- Firefox
-- Opera
-- Safari
+**Supported browsers:** Chrome · Brave · Chromium · Edge · Firefox · Opera · Safari
 
-Supported platforms:
-- macOS
-- Linux
-- Windows
+**Supported platforms:** macOS · Linux · Windows
 
-## Session Token
+On macOS, a Keychain prompt may appear on first use to authorize access to your browser's cookie encryption key. Click **Always Allow** to skip future prompts.
 
-The tool supports providing your own session token instead of reading from the browser. This enables use in environments where browser cookies are unavailable (such as CI).
+> [!NOTE]
+> **Windows + Chrome 127+:** Some versions of Chrome on Windows are not yet supported by the underlying cookie library. Use another browser or [investigate potential workarounds](https://github.com/drogers0/gh-image/issues/4).
 
-> **Warning:** `user_session` cookies grant full account access — they are not
-> scoped like personal access tokens. Treat them with the same care as a password.
-> Rotate promptly if leaked.
+### Session token override
 
-**Token resolution order (highest priority first):**
+For CI, headless environments, or shared machines, you can supply the session token explicitly. Resolution order (first match wins):
 
-1. `--token <value>` flag
-2. `GH_SESSION_TOKEN` environment variable
-3. Browser cookie extraction (default)
+| Priority | Source | When to use |
+|---|---|---|
+| 1 | `--token <value>` flag | One-off invocations |
+| 2 | `GH_SESSION_TOKEN` env var | CI/CD, shared machines |
+| 3 | Browser cookie store | Local interactive use (default) |
 
 ```bash
-# Use a token via flag
+# Flag (visible in process listings like `ps aux` — avoid on shared machines)
 gh image --token "$MY_TOKEN" screenshot.png --repo owner/repo
 
-# Use a token via environment variable (preferred on shared machines)
+# Environment variable (preferred — not visible to `ps aux`)
 GH_SESSION_TOKEN="$MY_TOKEN" gh image screenshot.png --repo owner/repo
 ```
 
-> **Security note:** `--token` values are visible in process listings (`ps aux`).
-> Use the `GH_SESSION_TOKEN` environment variable on shared machines.
+> [!WARNING]
+> `user_session` cookies grant **full account access** — they are not scoped like personal access tokens. Treat them with the same care as a password. If leaked, **[sign out of GitHub](https://github.com/logout)** on the machine that holds the session; if you are not on that machine, revoke it through [Settings → Sessions](https://github.com/settings/sessions), or [change your password](https://github.com/settings/security) (which kills every session in one action).
 
 
-## Token Utilities
+## CI / CD
 
-### `extract-token`
+`gh-image` runs unattended in GitHub Actions when given a session token via `GH_SESSION_TOKEN`.
 
-Extracts your session token from the browser and prints it to stdout. Useful for storing your token as a CI secret.
+> [!CAUTION]
+> **Use a dedicated bot account for CI/CD on shared repos.** GitHub hides secret values in the UI and masks log emissions, but a determined collaborator with write access can craft a workflow that exfiltrates the value through channels masking doesn't cover. Storing your *personal* `user_session` means such a leak compromises your account; a bot account scopes the blast radius to that bot. Decide whose token to extract in step 1 below accordingly.
 
-```bash
-# Extract and print token
-gh image extract-token
+**Setup**
 
-# Store in a variable
-TOKEN=$(gh image extract-token)
-```
+1. Run `gh image extract-token` locally to capture the token (token → stdout, status → stderr), then run `gh image check-token --token <token>` to confirm it authenticates as the intended user (username → stdout on success, exit code `0` = valid).
+2. Create a GitHub environment (Settings → Environments → New environment), e.g. `gh-image`, and restrict deployment branches to a trusted set (e.g. `main` only).
+3. Add the token as an **environment secret** named `GH_SESSION_TOKEN` on that environment.
 
-### `check-token`
+```yaml
+jobs:
+  upload:
+    runs-on: ubuntu-latest
+    environment: gh-image                                # binds this job to the scoped environment
+    steps:
+      - name: Upload screenshots
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}              # for gh CLI auth
+          GH_SESSION_TOKEN: ${{ secrets.GH_SESSION_TOKEN }}  # for the upload itself
+        run: |
+          gh extension install drogers0/gh-image
+          gh image check-token                                # optional: fail fast if the session expired
+          gh image screenshot.png --repo ${{ github.repository }}
+```
 
-Verifies that a session token is valid and, on a best-effort basis, prints the authenticated GitHub username to stdout. Exit code 0 means valid, exit code 1 means invalid or an error occurred. Username output may be empty even when the token is valid (for example, if the `<meta name="user-login">` tag is missing or cannot be parsed), so rely on the exit code for validity checks.
+> [!NOTE]
+> `user_session` cookies expire when GitHub invalidates the session. A scheduled `check-token` job is the cleanest way to detect expiry before it breaks a real run.
 
-```bash
-# Check token from flag
-gh image check-token --token "$MY_TOKEN"
+## How it works
 
-# Check token from environment variable
-GH_SESSION_TOKEN="$MY_TOKEN" gh image check-token
+1. Resolves a `user_session` cookie from the configured source (flag → env → browser).
+2. Fetches the target repository's page to obtain an `uploadToken` from the embedded JS payload.
+3. Requests an S3 upload policy from `/upload/policies/assets`.
+4. Uploads the file directly to S3 using the presigned form fields.
+5. Calls back to GitHub to finalize the asset.
+6. Prints `![name](url)` to stdout.
 
-# Check token from browser (default)
-gh image check-token
+The final URL is the standard `https://github.com/user-attachments/assets/<uuid>` format — visibility inherits from the target repository, so a private-repo upload requires authentication to view.
 
-# Capture username in a script
-USERNAME=$(gh image check-token --token "$MY_TOKEN")
-```
+For the full architecture, see **[documentation/architecture.md](documentation/architecture.md)**. For the reverse-engineered upload protocol, see **[documentation/github-image-upload-flow.md](documentation/github-image-upload-flow.md)**.
 
-## CI/CD Usage
+## Requirements
 
-> **Note:** `user_session` cookies are real user login sessions, not scoped automation credentials. They expire when GitHub invalidates the session. Use a pre-push hook or periodic job to validate the token (see `check-token`) and rotate it when needed.
+- A supported browser with an active GitHub session — or a `GH_SESSION_TOKEN` for CI.
+- Write access to the target repository (uploads require it).
+- A target repository — pass `--repo owner/repo`, or run from a git workspace whose `origin` remote is on GitHub.
+- The `gh` CLI must be installed and authenticated (used for repository ID lookup).
 
-### Setup
+## Limitations
 
-1. Extract your token locally:
-   ```bash
-   gh image extract-token
-   ```
-2. Add the output as a repository secret named `GH_SESSION_TOKEN` in your GitHub repository settings.
+- Uses an **undocumented** internal GitHub API that may change without notice.
+- `uploadToken` is only issued to users with write access on the target repository.
+- Session cookies are not scoped credentials; they expire when GitHub invalidates the session.
 
-### Example GitHub Actions workflow
+## Contributing
 
-```yaml
-- name: Upload screenshots
-  env:
-    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}         # Required for gh CLI auth
-    GH_SESSION_TOKEN: ${{ secrets.GH_SESSION_TOKEN }} # GitHub session token
-  run: |
-    gh extension install drogers0/gh-image
-    gh image --repo owner/repo screenshot.png
-```
+Issues and pull requests are welcome. For bug reports, please include:
 
-> **Note:** `gh` CLI must be authenticated (via `GH_TOKEN` or equivalent) for
-> extension installation and repository ID lookup. `GH_SESSION_TOKEN` is the
-> session token used for the image upload itself.
+- Your OS and browser
+- The exact `gh image` invocation
+- The error output (with any session token values redacted)
 
-### Validate token before upload
+Before opening a PR, run `go test ./...` and `go vet ./...`.
 
-```yaml
-- name: Validate session token
-  env:
-    GH_SESSION_TOKEN: ${{ secrets.GH_SESSION_TOKEN }}
-  run: gh image check-token
-
-- name: Upload screenshots
-  env:
-    GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-    GH_SESSION_TOKEN: ${{ secrets.GH_SESSION_TOKEN }}
-  run: |
-    gh extension install drogers0/gh-image
-    gh image --repo owner/repo screenshot.png
-```
+## Support
 
-### Cache extension for faster CI runs
+If `gh-image` saves you a few drag-and-drops, a ⭐ helps others find it:
 
-```yaml
-- name: Cache gh extensions
-  uses: actions/cache@v4
-  with:
-    path: ~/.local/share/gh/extensions
-    key: gh-extensions-${{ runner.os }}
+```bash
+gh api --method PUT user/starred/drogers0/gh-image
 ```
 
-## Requirements
+(or just click the star at the [top of this page](https://github.com/drogers0/gh-image))
 
-- A supported browser with an active GitHub session (for local use)
-- Write access to the target repository
-- For CI: a valid `GH_SESSION_TOKEN` secret (see [CI/CD Usage](#cicd-usage))
-
-## Limitations
+## License
 
-- This tool uses an undocumented GitHub internal API that could change without notice.
-- The `uploadToken` required for uploads is only available to users with write access to the target repository.
-- Either `--repo` must be provided or the tool must be run from within a git workspace with a GitHub remote.
-- Session tokens are not scoped credentials — they expire with the browser session and should be rotated periodically.
+[MIT](LICENSE) © 2025-2026 drogers0