docs: mark DISCOVERY_TOOL_DESIGN endpoints as Phase-2 not-yet-implemented (#3498) (#3599)

CHANGELOG.md

@@ -7,6 +7,7 @@
 - **fix(routing):** a valid `max_tokens`-truncated upstream response is no longer misclassified as empty content and rewritten into a fake 502 — `isEmptyContentResponse()` flagged any Claude `content:[]` / OpenAI empty-choice payload regardless of `stop_reason`/`finish_reason`, so a Claude Code `max_tokens: 1` connectivity ping (HTTP 200, `stop_reason:"max_tokens"`, empty content) became a synthetic `502 "Provider returned empty content"` and triggered a needless family fallback. The guard now treats a terminal truncation/tool signal (Claude `stop_reason` `max_tokens`/`tool_use`, OpenAI `finish_reason` `length`/`tool_calls`) as a legitimate completion; genuinely empty responses (no terminal reason, or `stop`/`end_turn` with empty content) are still caught. ([#3572](https://github.com/diegosouzapw/OmniRoute/issues/3572))
 - **fix(api):** `/v1/completions` now returns the legacy OpenAI Completions shape (`object:"text_completion"`, `choices[].text`) instead of chat payloads (`choices[].message|delta.content`) — the endpoint routes internally through the chat pipeline, so legacy Completion clients like TabbyML's `openai/completion` backend crashed with `missing field "text"`. The response (both non-streaming JSON and the SSE stream) is now translated back to the text-completion shape; `[DONE]` and error bodies pass through unchanged. ([#3571](https://github.com/diegosouzapw/OmniRoute/issues/3571))
 - **fix(usage):** the z.ai/GLM coding-plan quota card no longer shows "Monthly 0%" — coding plans have no monthly cap (only 5-hour windows), so the quota API reports the `TIME_LIMIT` ("Monthly") entry with `total=0`, and the `total>0 ? … : 0` fallback rendered a misleading 0% remaining (which can skew downstream model-choice). With no absolute cap the remaining percentage now falls back to the percentage-derived value (full/100% when 0% used). ([#3580](https://github.com/diegosouzapw/OmniRoute/issues/3580))
+- **docs(discovery):** mark `DISCOVERY_TOOL_DESIGN.md`'s API Endpoints table with an explicit "⚠️ Not yet implemented — Phase 2" banner — the discovery routes are a design proposal (Phase-1 stub only), and the banner makes clear the `KNOWN_STALE_DOC_REFS` gate suppression is intentional, not stale drift. ([#3498](https://github.com/diegosouzapw/OmniRoute/issues/3498))
 
 ---
 

docs/research/DISCOVERY_TOOL_DESIGN.md

@@ -83,6 +83,12 @@ CREATE TABLE discovery_results (
 
 ## API Endpoints
 
+> ⚠️ **Not yet implemented — Phase 2 (Future).** The routes below are a design
+> proposal, not live endpoints. `src/lib/discovery/index.ts` is an explicit Phase-1
+> stub and none of the discovery routes exist yet. They are intentionally documented
+> here as the planned surface; the `check-docs-symbols` quality gate suppresses them
+> via `KNOWN_STALE_DOC_REFS` until Phase 2 lands. See **Implementation Plan → Phase 2**.
+
 | Method | Path | Description |
 |--------|------|-------------|
 | GET | `/api/discovery/results` | List all discovery results |

scripts/check/check-docs-symbols.mjs

@@ -60,7 +60,9 @@ export const KNOWN_STALE_DOC_REFS = new Set([
   "/api/shadow/[id]",
   "/api/shadow/[id]/results",
   "/api/shadow/metrics",
-  // docs/research/DISCOVERY_TOOL_DESIGN.md — design doc de feature NÃO implementada: — #3498
+  // docs/research/DISCOVERY_TOOL_DESIGN.md — design doc de feature NÃO implementada
+  // (Phase 2). Refs INTENCIONAIS: o doc agora traz um banner "⚠️ Not yet implemented
+  // — Phase 2" acima da tabela de endpoints. Mantidos aqui até a feature existir. — #3498
   "/api/discovery/results",
   "/api/discovery/results/:id",
   "/api/discovery/scan",