docs: reposition github setup around workflows

Author: hack-cli-tests

README.md

@@ -123,6 +123,19 @@ bun run build:node-runtime-image --tag hack-node-runtime:dev
 
 Full operator guide: [`docs/guides/remote-node-container.md`](docs/guides/remote-node-container.md)
 
+### GitHub workflows (optional)
+
+Connect GitHub only when you want Hack to do GitHub work for you. Today that mainly means:
+
+- creating or updating PRs from `hack dispatch run --pr` or `hack x github pr-upsert`
+- helping the controller bootstrap a private GitHub repo onto a remote node when the node cannot
+  already clone it
+
+You do not need GitHub for local `hack init/up/open`, logs, tickets, or remote runs against public
+repos.
+
+Guide: [`docs/guides/github-workflows.md`](docs/guides/github-workflows.md)
+
 ### Tickets (optional, git-backed issue tracking)
 
 `hack` includes a lightweight, git-backed ticket system for tracking work without leaving your repo. Tickets are stored in a hidden git ref (`refs/hack/tickets`) so they sync with your code but don't clutter your branch list.

docs/README.md

@@ -34,6 +34,7 @@ Quick diagnostics:
 - Remote setup (one command): `hack remote setup`
 - [Initialize a project](guides/init-project.md)
 - [Global settings](guides/global-settings.md)
+- [GitHub workflows](guides/github-workflows.md)
 - [Tickets (git-backed)](guides/tickets.md)
 - [Expose the gateway over SSH](guides/remote-ssh.md)
 - [Expose the gateway with Cloudflare](guides/remote-cloudflare.md)

docs/cli.md

@@ -959,6 +959,9 @@ GitHub profile precedence for `--pr`:
 2. Project `controlPlane.routing.overrides.github.profile`.
 3. Global `controlPlane.extensions["dance.hack.github"].config.defaultProfile`.
 
+`--pr` requires GitHub auth to resolve for the selected profile. Set that up with
+`hack x github oauth-connect` or `hack x github connect` before using PR automation.
+
 #### hack dispatch status
 
 Usage: `hack dispatch status <run-id> [--json]`

docs/extensions.md

@@ -198,6 +198,36 @@ Options:
 
 ### GitHub extension (`hack x github`)
 
+Use GitHub when you want Hack to do GitHub work for you. GitHub is optional for core Hack setup
+and day-to-day local orchestration.
+
+GitHub currently unlocks:
+
+- PR automation from `hack dispatch run --pr` or `hack x github pr-upsert`
+- private GitHub repo bootstrap fallback for remote nodes when the node cannot clone on its own
+- explicit GitHub profile routing across Hack Desktop and the CLI
+
+You do not need GitHub for `hack init`, `hack up`, `hack open`, logs, tickets, or remote workflows
+against public repos.
+
+GitHub becomes required when:
+
+- you want Hack to create or update a GitHub PR
+- you want the controller to supply private GitHub clone credentials during remote bootstrap
+
+`Connect GitHub integration` is also separate from `Sign in to Hack with GitHub`. The first gives
+Hack a GitHub identity for GitHub-specific workflows. The second is only about Hack account auth.
+
+For the workflow-first guide, see [GitHub workflows](guides/github-workflows.md).
+
+Fastest setup paths:
+
+Interactive browser auth + installation picker:
+
+```bash
+hack x github oauth-connect --profile personal --set-default
+```
+
 Connect or update a profile directly from token input:
 
 ```bash
@@ -225,11 +255,9 @@ printf "%s" "$GITHUB_APP_PRIVATE_KEY" | hack x github connect \
   --private-key-auth-ref github.app.private_key.default
 ```
 
-One-click browser OAuth bootstrap (via `gh`) + installation picker:
+Optional non-interactive installation bind with browser OAuth:
 
 ```bash
-hack x github oauth-connect --profile personal --set-default
-# optional non-interactive installation bind:
 hack x github oauth-connect --profile personal --installation-id 12345678
 ```
 

docs/guides/github-workflows.md

@@ -0,0 +1,113 @@
+# GitHub Workflows
+
+Use GitHub when you want Hack to do GitHub work for you.
+
+GitHub is not part of the base Hack setup. You do not need it for `hack init`, `hack up`,
+`hack open`, logs, local sessions, tickets, or public-repo remote workflows.
+
+GitHub currently unlocks three things:
+
+1. PR automation from Hack.
+2. Private GitHub repo bootstrap on remote nodes when the node cannot already clone the repo.
+3. A named GitHub profile that Hack Desktop and the CLI can route explicitly.
+
+This is also separate from signing in to Hack with GitHub. `Sign in to Hack` controls your Hack
+account. `Connect GitHub integration` gives Hack a GitHub identity it can use for GitHub-specific
+workflows.
+
+## When GitHub Is Optional
+
+Leave GitHub disconnected if you are only using Hack for:
+
+- local orchestration
+- project routing and HTTPS
+- logs and diagnostics
+- tickets or Linear workflows
+- remote execution against public repos
+- remote execution where the node already has working Git credentials
+
+## When GitHub Is Required
+
+Connect GitHub when you want either of these workflows:
+
+- `hack dispatch run --pr` or `hack x github pr-upsert`
+- controller-assisted clone fallback for a private GitHub repo on a remote node
+
+If the remote node can already clone the repo on its own, GitHub stays optional even for remote
+execution.
+
+## Fastest Setup By Goal
+
+### 1. Interactive setup for a person using Hack
+
+Use browser auth and pick an installation:
+
+```bash
+hack x github oauth-connect --profile personal --set-default
+```
+
+Use this when you want the simplest path to PR automation or private-repo fallback.
+
+### 2. Bring an existing token
+
+Use this when you already manage a token outside Hack:
+
+```bash
+hack x github connect --profile default --token-env HACK_GITHUB_APP_TOKEN
+
+# or:
+printf "%s" "$HACK_GITHUB_APP_TOKEN" | hack x github connect --profile default --stdin
+```
+
+### 3. Use GitHub App credentials for least privilege
+
+Use this when you want installation-scoped auth that can refresh automatically:
+
+```bash
+hack x github connect \
+  --profile work \
+  --set-default \
+  --app-id 12345 \
+  --installation-id 67890 \
+  --private-key-env HACK_GITHUB_APP_PRIVATE_KEY
+```
+
+## Common Commands
+
+```bash
+hack x github profiles
+hack x github use --profile work
+hack x github status --profile work
+hack x github disconnect --profile work
+```
+
+PR creation/update:
+
+```bash
+hack x github pr-upsert \
+  --profile work \
+  --repo owner/repo \
+  --head my-branch \
+  --base main \
+  --title "My PR" \
+  --body "Details"
+```
+
+## Profile Selection
+
+Hack resolves the GitHub profile in this order:
+
+1. `--profile`
+2. `controlPlane.routing.overrides.github.profile`
+3. `controlPlane.extensions["dance.hack.github"].config.defaultProfile`
+
+Use separate profiles when you need different GitHub identities for different repos or automations.
+
+## Browser Auth Requirements
+
+`hack x github oauth-connect` needs the GitHub OAuth app config in global Hack config:
+
+- `controlPlane.extensions["dance.hack.github"].config.oauthClientId`
+- `controlPlane.extensions["dance.hack.github"].config.oauthClientSecretAuthRef`
+
+The referenced secret is stored in the OS keychain under service `hack-github-auth`.

docs/guides/remote-node-laptop-e2e.md

@@ -129,6 +129,10 @@ Expected:
 
 ### Private repo bootstrap behavior (default, no manual copy)
 
+GitHub is optional for public repos or for private repos when the remote machine already has working
+Git credentials. It becomes required only when Hack needs to supply controller-side credentials for
+private GitHub clone fallback.
+
 Workspace bootstrap now uses this order automatically:
 1. Attempt clone with the remote machine's existing Git credentials.
 2. If clone fails and origin is GitHub, retry with controller GitHub token auth (from `hack x github connect` or `HACK_GITHUB_APP_TOKEN`).

docs/guides/remote-node-quickstart.md

@@ -9,6 +9,9 @@ Use this guide to connect one remote machine as a `hack` execution node and run
 3. SSH access from host to remote (`user@host`).
 4. A reachable gateway endpoint on the remote (`http://<host>:7788` or tailnet URL).
 
+GitHub is optional here. You only need it if the repo is private on GitHub and the remote machine
+cannot already clone it with its own credentials.
+
 ## Step 1: prepare the remote machine
 
 Run on the remote machine:
@@ -70,6 +73,15 @@ hack dispatch run \
   -- "pwd"
 ```
 
+If this project is a private GitHub repo and the remote node cannot clone it directly, connect
+GitHub on the controller first:
+
+```bash
+hack x github oauth-connect --profile work --set-default
+```
+
+See [GitHub workflows](github-workflows.md) for the full optional-vs-required breakdown.
+
 Optional remote check:
 
 ```bash
@@ -102,3 +114,6 @@ You can do the same flow in Hack Desktop:
 4. Local project URL fails after remote dispatch (`https://<project>.hack`):
    - run `hack node routes status` then `hack node routes repair`.
    - if global proxy is down, run `hack global up` and retry.
+5. Remote bootstrap fails on a private GitHub repo:
+   - connect GitHub on the controller so Hack can retry clone with controller credentials.
+   - run `hack x github oauth-connect --profile work --set-default` and retry.

src/control-plane/extensions/github/commands.ts

@@ -102,7 +102,7 @@ export const GITHUB_COMMANDS: readonly ExtensionCommand[] = [
   {
     name: "connect",
     summary:
-      "Store a GitHub token in keychain and persist profile config (direct or App exchange)",
+      "Connect GitHub for PR automation or remote repo bootstrap (token or App)",
     scope: "global",
     handler: async ({ ctx, args }) => {
       const parsed = parseConnectArgs({ args });
@@ -181,7 +181,7 @@ export const GITHUB_COMMANDS: readonly ExtensionCommand[] = [
   {
     name: "oauth-connect",
     summary:
-      "Open browser GitHub auth via gh CLI, import token, and bind selected profile",
+      "Connect GitHub in a browser and import a profile for Hack workflows",
     scope: "global",
     handler: async ({ ctx, args }) =>
       await handleGitHubOAuthConnectCommand({