docs(bot): unquoted placeholder values so scan examples aren't findings

[samson910022]

Last dry_run had 2 nit findings left, both our own quoted '...' placeholders in docs examples. Rewrite as unquoted your-*-here placeholders. Live scan now reports 0 findings; next real run will only file true signal.

[github-actions]

Verdict matrix

• Roles: gateway_safety, api_compat, docs_config
• FINAL_VERDICT: COMMENT

Sensitive paths

• .env.example
• github_bot/README.md
• src/proxy.ts

Deterministic pre-checks

• (none)

gateway_safety

VERDICT: APPROVE

RATIONALE

• Checklist 1 (No secrets): Placeholders in documentation and .env.example follow safety conventions (your-[provider]-url-here, [REDACTED]); no secret values or sensitive local paths committed.
• Checklist 2 (Auth discipline): src/proxy.ts diff is purely documentation/comment clarification regarding API key verifier instantiation; no auth logic was modified.
• Checklist 3 & 4 (Tools & Port Matrix): Tool defaults remain intact; documentation updates in docs/configuration.md accurately document existing config-matrix keys and fallbacks.
• Code hygiene: Replaces duplicate local asRecord in src/search/grounding.ts with the canonical shared utility from src/utils/guards.js.

api_compat

API Compatibility Review

Summary

This PR is primarily a documentation/placeholder cleanup to eliminate false-positive scan findings, with two minor code changes. The diff touches no route handlers, wire-shape logic, converters, session management, retry logic, or model alias rules.

---

Checklist evaluation

#	Area	Status	Notes
1	Wire shapes (chat/responses/messages/interactions error exits)	✅ Unchanged	No route handler changes
2	Converter thinking/signature preservation	✅ Unchanged	No converter changes
3	previous_response_id / session chaining	✅ Unchanged	No session logic changes
4	Reasoning mapping thresholds	✅ Unchanged	Not touched
5	Model alias rules	✅ Unchanged	Not touched
6	Collector finish==='tool' / flushHeaders	✅ Unchanged	Not touched
7	resolveMaxRetries clamp / backoff / jitter	✅ Unchanged	Not touched
8	New endpoints documented	N/A	No new endpoints

---

Findings

BLOCKING: (none)

SHOULD_FIX:

1. docs/configuration.md:108 — OPENCODE_SERVER_PASSWORD and ZEN_API_KEY shown as empty strings in example JSON block.
   While these are short keys (not env vars) and the values are empty "", showing password/key fields even with empty values in a public doc example could encourage copy-paste with real values later. Consider using a comment-style placeholder like "your-password-here" or omitting them entirely (they already appear in the env table above). Severity: should-fix (consistency with the PR's own stated goal of using your-*-here placeholders).

2. src/proxy.ts:103-106 — Comment-only change is accurate but could be more precise.
   The new comment says "each copies at construction (spread in system routes, filter in keys)" — this is helpful context, but the parenthetical filter in keys is slightly ambiguous about which filter call. Minor documentation clarity issue. Severity: nit (reclassified below).

NITS:

• src/search/grounding.ts:6 — Moving asRecord to a shared utils/guards.ts import is a good dedup. Confirm the removed local definition was the only call site in this file (it was — toolTypeOf uses it). No behavioral change. ✅

• docs/AI_BOT.md:85 — CPA_API_KEY=[REDACTED] is now unquoted in a bash export line. This is fine for placeholder text but note that if someone copies this literally, [REDACTED] will be treated as a glob pattern by some shells. The your-*-here style used for CPA_BASE_URL is safer; consider CPA_API_KEY=your-[provider]-key-here for consistency.

• github_bot/README.md:39-41 — Same observation: GATEWAY_API_KEY=[REDACTED] and CPA_API_KEY=[REDACTED] use [REDACTED] while CPA_BASE_URL uses your-[provider]-url-here. Inconsistent placeholder style within the same code block.

• .env.example:32 — Adding OPENCODE_SERVER_URL as a commented-out example is fine; value http://127.0.0.1:10001 matches the documented default. ✅

• README.md / README.zh-CN.md — Node.js badge bump from 18+ to 22.19+ aligns with the project's engines field. ✅

• docs/development.md:14 — Comment updated to >=22.19 (engines floor; CI uses 24). Accurate. ✅

• docs/configuration.md:75 — New OPENCODE_PROXY_MANAGE_BACKEND row documents the known prod-vs-library default divergence. Good transparency. ✅

• docs/configuration.md — New config.json keys (HEALTH_DETAILS_ENABLED, HEALTH_DETAILS_REQUIRE_AUTH, METRICS_ENABLED, METRICS_REQUIRE_AUTH, UPSTREAM_PROXIES, UPSTREAM_PROXY_STRATEGY, UPSTREAM_PROXY_COOLDOWN_MS, UPSTREAM_PROXY_NO_PROXY) document existing runtime behavior. No wire-shape impact. ✅

---

Test gaps

• No test changes in this PR, which is appropriate for a docs-only + minor refactor PR.
• The asRecord extraction to utils/guards.ts should already be covered by existing grounding tests; worth confirming grounding.test.ts still passes (CI should catch this).

---

VERDICT: APPROVE

The two code changes (comment clarification in proxy.ts, asRecord import consolidation in grounding.ts) are safe and behavioral-neutral. Documentation updates are accurate and improve scan signal quality. The should-fix on empty password/key placeholders in config.json example and the nit on inconsistent [REDACTED] vs your-*-here placeholder style are worth addressing but not blocking.

docs_config

VERDICT: COMMENT

BLOCKING:

• none in-diff. No secrets committed, no wire-shape change, no docs/host-deployments.md link, no npm run lint ref.

SHOULD_FIX:

• Six-way sync unverified (tools disabled) for touched envs. Confirm canonical names exist in all 6 + AGENTS.md table, or list gaps:
  • .env.example:32 adds # OPENCODE_SERVER_URL=http://127.0.0.1:10001 — verify config.json.example, Dockerfile, docker-compose.yml, index.ts, docs/configuration.md:108, AGENTS.md already have canonical OPENCODE_SERVER_URL.
  • docs/configuration.md:75 adds OPENCODE_PROXY_MANAGE_BACKEND row + docs/configuration.md:111 "MANAGE_BACKEND": false — verify .env.example, config.json.example, Dockerfile, docker-compose.yml, index.ts, AGENTS.md already cover it; if not, those files must change to close gap, not docs alone.
  • docs/configuration.md:96-113 adds HEALTH_DETAILS_ENABLED, HEALTH_DETAILS_REQUIRE_AUTH, METRICS_ENABLED, METRICS_REQUIRE_AUTH, OPENCODE_SERVER_PASSWORD, ZEN_API_KEY, UPSTREAM_PROXIES, UPSTREAM_PROXY_STRATEGY, UPSTREAM_PROXY_COOLDOWN_MS, UPSTREAM_PROXY_NO_PROXY to example JSON — verify each has canonical env + file short-key + index.ts + container files + AGENTS.md; docs-only addition otherwise widens drift.
• Known drifts preserved correctly — no silent fix:
  • docs/configuration.md:75 explicitly notes prod/index.ts false vs library/buildProxyConfig true for MANAGE_BACKEND — good.
  • docs/configuration.md:108-111 keeps REQUEST_TIMEOUT_MS: 180000, OMIT_SYSTEM_PROMPT: false — good, do not normalize to library defaults.
• docs/configuration.md:33 OPENCODE_DISABLE_TOOLS / DISABLE_TOOLS with canonical-wins wording matches resolveDisableTools order — good, no code change to resolution in src/proxy.ts:103-106 (comment-only).

NITS:

• README.md:6, README.zh-CN.md:6, docs/development.md:14 Node floor 22.19+ in sync EN/ZH + dev doc — good. No docs/README.md index update needed unless per-file status tracks Node floor.
• docs/AI_BOT.md:85, github_bot/README.md:39-41 your-[provider]-url-here unquoted placeholder — correct fix for scanner nit, no secret value.
• src/search/grounding.ts:6 asRecord dedup to ../utils/guards.js — out-of-scope for docs/config; defer semantic equivalence to code reviewer.
• No CHANGELOG.md entry — acceptable for bot placeholder hygiene if repo convention exempts; otherwise add EN-first entry.

Files that must change to close gap (if verification fails):

• config.json.example, Dockerfile, docker-compose.yml, index.ts, AGENTS.md — only if canonicals above missing there. No additional change required if they already contain them.

FINAL_VERDICT: COMMENT

Session: response_id=resp_20aiat3vDb6i9tMPjZjWiAo,resp_req_vrtx_011CeuF1x3uWeQYXquyxru63,chatcmpl-e2be49e1-4299-4df4-a7b8-6c53646004b2 (chain via previous_response_id, 30min TTL). model=[model] provider=[provider].