docs: reference GEMINI_API_KEY env var in curl examples so gitleaks can be bumped

[groupthinking]

Canonical issue

Closes #1217

Outcome

The Secret Scan workflow pins GITLEAKS_VERSION="8.18.4" (.github/workflows/secret-scan.yml). Any bump past that pin fails on main — not because a secret was introduced, but because newer gitleaks ships a default curl-auth-header rule that this repository's documentation trips.

Two curl snippets in the universal-automation-service prototype notes embedded a scrubbed credential marker directly in an auth header:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash-exp:generateContent" \
  -H 'Content-Type: application/json' \
  -H 'X-goog-api-key: REDACTED_GOOGLE_API_KEY_ROTATE' \
  ...

REDACTED_GOOGLE_API_KEY_ROTATE is a leftover marker from the credential purge, not a live key — but curl-auth-header matches on the shape of the invocation, not the value's entropy, so it fires regardless. Because the rule does not exist in 8.18.4, the failure is invisible today and only detonates for whoever bumps the pin, on a change unrelated to theirs.

This PR removes the trigger at its source: the snippets now read the key from the environment.

-  -H 'X-goog-api-key: REDACTED_GOOGLE_API_KEY_ROTATE' \
+  -H "X-goog-api-key: ${GEMINI_API_KEY}" \

That is a two-line change to a documentation file, and it is also simply better documentation — a runnable example that teaches sourcing the key from the environment rather than pasting it into a shell history.

Why not an allowlist

Adding a .gitleaks.toml entry was the obvious alternative and was rejected on three grounds:

1. It would suppress, not fix. Any allowlist broad enough to cover this finding also covers a future real key pasted into the same file in the same shape. The whole point of the scanner is to catch that.
2. It would probably not even work. The finding's reported line is the curl "https://..." line, not the -H line — the rule matches across the multi-line invocation. The repo's single global [allowlist] block sets regexTarget = "line", so a regex written against REDACTED_ would be matched against a line that does not contain it. Making it work would mean a path allowlist for docs/knowledge_prototypes/.*, retiring an entire docs tree from scanning.
3. It is permanent debt for a transient artifact. The marker exists only because of a past incident cleanup. Deleting it costs nothing.

No .gitleaks.toml change is included in this PR.

Scope

• Included: the two -H lines in docs/knowledge_prototypes/universal-automation-service/TECHNICAL_NOTES.md (lines 32 and 203). One file, two lines, no code.
• Explicitly excluded — and deliberately so: the other ~18 REDACTED_GOOGLE_API_KEY_ROTATE occurrences across FINAL_STATUS.md, RUN_WITH_VENV.md, SETUP.md, COMPREHENSIVE_SYSTEMS_STATUS.md and elsewhere in this file. I checked each: they are export GEMINI_API_KEY="..." lines and historical incident notes, they match no gitleaks rule at either version, and rewriting them would turn a targeted CI fix into a sprawling docs diff with no security benefit.
• Excluded: bumping GITLEAKS_VERSION itself. This PR proves the bump is safe; choosing the target version and re-pinning is a separate, deliberate maintenance decision that should not ride along with a docs change.

Risk

• Risk level: low. Two lines in a Markdown file inside docs/knowledge_prototypes/. No source, config, workflow, test, or dependency is touched; nothing is imported, built, or executed from this path.
• Failure mode: the worst realistic outcome is a documentation regression — a reader copies the snippet without GEMINI_API_KEY exported and gets a 401 from Google instead of a 200. The previous snippet returned a 400/401 too, since the value it carried was a redaction marker rather than a working key, so the copy-paste experience is strictly improved, not degraded.
• Rollback: git revert of a single documentation commit. No migration, no state, no coupling to any other change.
• Counter-risk of not merging: the next person to touch GITLEAKS_VERSION gets a red Secret Scan on main and a false "we leaked a Google API key" signal, which is exactly the alarm-fatigue outcome a secret scanner must avoid.

Verification

Run against head of this branch, using the exact command from .github/workflows/secret-scan.yml:

gitleaks detect --no-git --config .gitleaks.toml --redact --verbose --exit-code 1

Both the currently pinned version and a much newer one were executed locally, before and after the change, giving a full 2×2 matrix rather than a one-sided claim:

gitleaks	before this PR	after this PR
8.18.4 (current CI pin)	no leaks found, exit 0	no leaks found, exit 0
8.30.0 (12 minor releases ahead)	2 leaks, exit 1, RuleID: curl-auth-header, TECHNICAL_NOTES.md lines 30 and 201	no leaks found, exit 0

• Reproduced the reported failure first — 8.30.0 on unmodified main produced exactly the two findings described in Secret Scan will break on any gitleaks version bump: curl-auth-header flags placeholder in TECHNICAL_NOTES.md #1217, with the rule ID and both line numbers matching. The fix was written against a confirmed reproduction, not a hypothesis.
• Fix verified — 8.30.0 now reports no leaks found and exits 0. This is the acceptance criterion in Secret Scan will break on any gitleaks version bump: curl-auth-header flags placeholder in TECHNICAL_NOTES.md #1217: the pin can be bumped without the scan going red.
• No regression on the pinned version — 8.18.4 still reports no leaks found and exits 0, so today's CI is unaffected. The stashed-vs-restored runs above confirm 8.18.4 was green both before and after, isolating the change's effect to the newer version only.
• Scan coverage unchanged — 63.74 MB scanned across the working tree, identical to the pre-change run. Nothing was excluded to achieve the pass; the finding is gone because its cause is gone.
• 8.18.4 binary provenance — downloaded from github.com/gitleaks/gitleaks/releases/download/v8.18.4/, gitleaks version confirms 8.18.4, matching the pin byte-for-byte rather than assuming a locally-installed build behaves the same.
• Lint / tests — not applicable and not skipped: git show --stat confirms the commit touches exactly one .md file, so no Python, TypeScript, or workflow code paths are reachable by this diff.

Known-failing check, pre-existing and repo-wide: Agent completion enforcement requires a check run named Agent Lock trusted publication from a trusted GitHub App, and .github/agent-lock/trusted-publishers.json ships with empty allowlists under custom_role_policy: "fail_closed", with a note stating this "intentionally blocks". It fails on every open PR here (verified on #1122, #1207, #1216) and is tracked separately in #1160, which explicitly asks for a human decision.

Production evidence

Not applicable as a runtime artifact, for a specific rather than blanket reason: the diff is confined to a Markdown file under docs/knowledge_prototypes/, which is not imported by the Python package, not part of the Next.js build, and not served by any route. There is no deployed surface for this change to alter and therefore nothing to exercise in a preview environment.

The evidence that matters for a CI-hygiene fix is the CI behaviour itself, and it is recorded above as real command output from two independently downloaded gitleaks binaries run against the real working tree — a genuine before/after reproduction rather than an assertion that the change "should" work.

Agent handoff

• One canonical issue is linked (Secret Scan will break on any gitleaks version bump: curl-auth-header flags placeholder in TECHNICAL_NOTES.md #1217)
• No competing PR implements the same issue — no other open PR touches TECHNICAL_NOTES.md or .gitleaks.toml
• Acceptance criteria satisfied — Secret Scan will break on any gitleaks version bump: curl-auth-header flags placeholder in TECHNICAL_NOTES.md #1217 asked that a gitleaks bump not fail the scan; the 2×2 matrix above demonstrates exactly that
• Required checks pass on this head, with the one pre-existing repo-wide exception documented under Verification
• Follow-up left to a human by design: the actual GITLEAKS_VERSION bump. This PR makes it safe; it does not decide which version to move to.

---

🤖 Generated with Copilot CLI

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
v0-uvai	Ready	Preview, v0	Aug 2, 2026 12:35pm

[coderabbitai]

Important

Review skipped

Auto reviews are limited based on label configuration.

🏷️ Required labels (at least one) (1)

• [‘architecture-gap’, ‘bug’, ‘ci-cd’, ‘ci/cd’, ‘copilot-rabbit’, ‘documentation’, ‘duplicate’, ‘enhancement’, ‘frontend’, ‘github_actions’, ‘good first issue’, ‘help wanted’, ‘high-priority’, ‘invalid’, ‘javascript’, ‘ml-model’, ‘needs-triage’, ‘pipeline-critical’, ‘placeholder-code’, ‘priority:high’, ‘python’, ‘python:uv’, ‘question’, ‘styling’, ‘tests’, ‘v0’]

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited), Organization UI (inherited)

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 8550f692-f4ea-4ab9-a459-74987cad8d4f

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Snapshot Warnings

⚠️: No snapshots were found for the head SHA 2af0733.

Ensure that dependencies are being submitted on PR branches and consider enabling retry-on-snapshot-warnings. See the documentation for more information and troubleshooting advice.

Scanned Files

None

[github-actions]

Agent Completion Truth Gate: NOT_APPLICABLE

Evidence agrees.

Machine-readable verdict

{
  "details": {},
  "reasons": [],
  "verdict": "not_applicable"
}

Workflow evidence

[Copilot]

Pull request overview

Updates Gemini curl examples to source credentials from the environment, preventing newer gitleaks false positives and resolving #1217.

Changes:

• Replaces two redacted credential markers with ${GEMINI_API_KEY}.
• Keeps secret scanning enabled without adding allowlists.

[groupthinking]

🟢 Merge-ready — awaiting human sign-off

Automated remediation pass (terminal-state record).

Substantive state: this is a two-line documentation change (docs/knowledge_prototypes/universal-automation-service/TECHNICAL_NOTES.md) that reads GEMINI_API_KEY from the environment instead of embedding the scrubbed REDACTED_GOOGLE_API_KEY_ROTATE marker, so a future GITLEAKS_VERSION bump won't trip the newer curl-auth-header rule. No code, config, workflow, or dependency is touched.

Checks: combined commit status success on head 2af0733 — Vercel preview deployed, agent-completion/truth-gate not_applicable, CodeRabbit review skipped by label config (documentation-only). No review threads to resolve.

One red remains — repo-wide, not this PR's fault: Agent completion enforcement (missing_trusted_publication) looks for an Agent Lock trusted publication check from a trusted GitHub App that is not provisioned in this repo, so it fails closed on essentially every PR here. It is non-required — this PR is mergeable, state unstable, not blocked. The systemic fix is tracked by #1151 / #1154.

Terminal state: HALTED(awaiting_merge_approval). Merge to protected main is the irreversible human gate — not auto-merged. Staged next step for a maintainer:

gh pr merge 1219 --repo groupthinking/EventRelay --squash

Accept the non-required Agent completion enforcement red, or land #1151 first to neutralize that gate repo-wide, then merge.

---

Generated by Claude Code

[groupthinking]

Review verdict: LGTM (posted as a comment — GitHub blocks approving one's own PR). Reviewed at head 2af0733.

This is a correct, minimal, low-risk fix. Verified:

• Diff is exactly as described: two -H lines in docs/knowledge_prototypes/universal-automation-service/TECHNICAL_NOTES.md, swapping the REDACTED_GOOGLE_API_KEY_ROTATE marker for ${GEMINI_API_KEY}. Docs-only — nothing under this path is imported by the Python package, built into apps/web, or served by a route, so there is no runtime surface to regress.
• Change is sound: the single→double quote switch is required for ${GEMINI_API_KEY} expansion in the curl snippets. Sourcing the key from the environment removes the curl-auth-header shape that newer gitleaks matches on — precisely the CI-hygiene goal of #1217 — and is also better documentation than a pasted literal.
• Scope discipline is right: leaving the ~18 other export GEMINI_API_KEY="..." occurrences untouched is correct — they match no gitleaks rule at either version. Choosing not to add a .gitleaks.toml allowlist is also the right call — an allowlist broad enough to cover this would mask a future real key pasted in the same shape.
• CI: required checks are green (build, test, lint-python, lint-frontend, bandit, trivy, CodeQL, gitleaks (working tree), dependency-review, security scans). The one failing check, Agent completion enforcement, is the pre-existing repo-wide fail-closed governance gate (empty trusted-publisher allowlist, tracked in #1160); it fires on every open PR and is not introduced by this diff. The newer agent-completion/truth-gate reports not_applicable / all rules passed, and mergeable_state: unstable is due to that non-required check, not a merge conflict.

Not merging from here: the publish decision belongs to a human. This PR carries only the documentation label (not automerge) and targets protected main, so the merge click stays with you. The follow-up GITLEAKS_VERSION bump this PR makes safe is likewise a separate, deliberate maintenance step.

---

Generated by Claude Code

[groupthinking]

Returned to draft during delivery control. The documentation-only change is linked to #1217, but no current execution receipt has been reconciled. Preserve the branch; do not advance until the focused unit and exact-head evidence are bound.

[linear-code]

GRV-285