acq: loud/gated kit-fetch fallback + docs for git-credential vs gh auth (public kit fetch) #208

Summary

Two smaller issues surfaced alongside the interactive-prompt bug (#) in acq.backends/kit-translate.sh, split out so # stays a focused code fix.

1. Silent "pass ref through to sbx on failure" masks the real failure

On a kit fetch failure, acq emits warning: could not fetch kit; passing ref through: … and hands the raw ref to the sbx backend. The consensus panel flagged this as the single biggest risk: it masks the real error (the user sees a confusing downstream git-password error rather than a clear kit-fetch failure) and can silently run against a stale/unexpected ref.

Change (not remove — removal could break workflows that rely on passthrough): make the warning loud and actionable (name the fetch error + remedy), and consider gating passthrough behind an explicit opt-in (env/flag) so the default fails loudly. Keep backward-compat with a deprecation note if we later default it off.

2. Docs: git-credential vs gh auth, and the public-repo fetch

The kit repo (GSA-TTS/agentic-coding-patterns) is public — the fetch should need no credentials. But users with a global git credential helper or url.*.insteadOf rewrite hit friction with no documented remedy. Add:

• A KNOWN_FAILURE_MODES entry: symptom (Username for 'https://github.com': prompt during acq run), cause (gh CLI auth ≠ git credential; a global helper/insteadOf forces auth on a public clone), fix (gh auth setup-git, or inspect git config --global --get-regexp 'url\..*insteadOf'), and the egress-restricted/enterprise-mirror caveat.
• A short note in the acq docs (docs/explorations/acq-design.md or the acq usage docs) clarifying the same distinction.

Provenance

Found via a real user report (kit fetch prompting for GitHub credentials during acq run) + a consensus design review. Companion to # (the non-interactive fetch fix).