docs(agents): gh-via-1Password patterns + launchctl host setup

[arv]

What

Documents how gh authentication actually works under agents v2.0.0 — the
setup turned out to be non-obvious in practice, so this captures it.

• Re-applies the local-vs-headless split that didn't make it into feat(agents)!: authenticate gh via 1Password #6 (the
  squash merged just before that commit, so main's README still had the old
  single-pattern version):

  • Pattern A — local dev container (recommended): resolve the token on the
    host, forward GITHUB_TOKEN via remoteEnv, no ghTokenSecretRef. Leads
    with the key non-obvious fact: 1Password's desktop-app/Touch ID
    integration does not work inside a container, so op can't run there.
  • Pattern B — headless (Codespaces/CI): in-container op read via
    ghTokenSecretRef + a scoped service-account token.

• Expands the host setup with launchctl coverage — the practical path for
  Dock/Spotlight launches and the no-checkout "Clone Repository in Container
  Volume" flow, where you never launch the editor from a terminal:

  • launchctl setenv GITHUB_TOKEN "$(op read '…')", with the caveats that you
    must relaunch the editor, it's cleared on logout/restart, and it's
    session-wide.
  • An optional collapsible LaunchAgent to re-apply it at login (with the
    caveat that op read only works non-interactively if 1Password can
    authorize without a prompt).
  • Keeps the terminal-launch option as the scoped alternative.
  • Documents the gotchas we actually hit: installing op without a package
    manager, and ~/.zshrc vs ~/.zsh_rc.

• Makes the generic Usage example neutral (no ghTokenSecretRef baked in)
  and points it at the two patterns.

Docs only — no feature behavior change.

---

Generated by Claude Code