docs(#1970): document githubAccount + gh/git integration + hivectl github set-token

docs/github.md

@@ -0,0 +1,72 @@
+# GitHub accounts
+
+Give an agent a managed GitHub identity — a `gh` CLI and `git push` over
+HTTPS, both authenticated as a configured bot account — so it can run
+GitHub API calls and push commits without any manual `gh auth login`.
+
+This mirrors the [matrix account](matrix.md) pattern: nix carries the
+login + host, never the secret; an operator-supplied personal access
+token (PAT) is injected out of band into the agent's state dir.
+
+## Config option
+
+Declare `hyperhive.githubAccount` in the agent's `agent.nix`:
+
+```nix
+hyperhive.githubAccount = {
+  username = "the-sword-above";                       # the bot login
+  tokenFile = "/agents/<name>/state/github-token";    # where the PAT lives
+  # host = "github.com";                              # default; set for GHE
+};
+```
+
+`null` (the default) leaves GitHub off entirely — no `gh` wrapper, no
+credential helper, no env. Single account per agent by design (unlike
+`matrixAccounts`, which is multi-account): the workflow is "this agent is
+this one bot".
+
+The token **value** is never in nix. `tokenFile` only names the path; the
+PAT is written there separately (see [Provisioning](#provisioning)).
+
+## How the agent uses it
+
+When `githubAccount` is set, the container gets:
+
+- **A `gh` wrapper** on `PATH` (shadowing the raw `gh`) that exports
+  `GH_TOKEN` from the token file at invocation, then execs real `gh`. So
+  `gh pr create`, `gh api …`, etc. just work as the bot.
+- **A git credential helper** (`git-credential-hive-github`), wired via a
+  host-scoped `/etc/gitconfig` entry for `https://<host>`, so
+  `git push https://github.com/<owner>/<repo>` authenticates as the bot.
+  Host-scoped, so it never touches the forge (`localhost:3000`) or any
+  other remote.
+- **Env**: `HIVE_GITHUB_USER`, `HIVE_GITHUB_HOST`,
+  `HIVE_GITHUB_TOKEN_FILE`, and `GH_HOST`.
+
+Both the wrapper and the credential helper read the token from the file
+**at invocation time**, so a PAT written (or rotated) mid-session takes
+effect immediately — no container rebuild or restart. Until the file
+exists, `gh` / `git push` simply fail unauthenticated.
+
+## Provisioning
+
+The PAT is operator-supplied. Write it into the agent's token file with:
+
+```sh
+hivectl github set-token <agent> --token-stdin   # paste the PAT on stdin (preferred)
+hivectl github set-token <agent> --token <pat>    # inline (visible in shell history)
+```
+
+hive-c0re delegates the write to hive-priv, which stores the file `0600`
+owned by the agent (so the container can read it) — the same credential
+injection path as forge/matrix tokens. See
+[hivectl → GitHub](tools/hivectl.md#github).
+
+## Security
+
+- Use a **dedicated bot account**, never a human's.
+- Mint a **minimally-scoped PAT** — only the repos/scopes the agent's
+  workflow needs. Agents have passwordless sudo, so a compromised or
+  hallucinating agent can act as the account within the token's scopes;
+  scope is the real blast-radius limiter, and the container boundary is
+  the enforcement. See [security.md](security.md).