build(docs): scaffold + document docs-search provisioning (search dead for all users) [DRAFT]

[mangrove-one]

⚠️ DRAFT — this scaffolds + documents the fix but does NOT make search return results on its own; turning search on is a product/infra decision (issue #85).

BLUF

The docs-site search box at docs.mangrovedeveloper.ai is dead for everyone, signed in or
not — it has no search backend. The tester saw it as "Login into CLI to enable search" with
no usable input (older/local-CLI client); the current client shows a "Search…" box that
simply returns nothing. Root cause is architecture, not content: we self-host Mintlify's
pre-built client, but Mintlify search is a hosted feature (a cloud vector DB with the site's
content indexed into it) that the self-hosted build never provisions.

This PR makes the build side explicit and documents the decision; it is a draft because a
working fix requires choosing one of three provisioning paths (below), each needing a Mintlify
account/secret or a new self-hosted search service. It clears the draft once a chosen backend
is provisioned and a real query through POST /_mintlify/api-public/search/<subdomain> returns
results (i.e. the human picks an option in #85 and wires the backend + indexed content).

What's wrong (precise routes)

Reverse-engineering the pinned client (mintlify@4.2.414) shows the two search surfaces and the
unset backends they forward to:

Surface	Client route	Forwards to	Needs
Public search box (no login)	POST /_mintlify/api-public/search/<subdomain>	${API_ENDPOINT:-http://localhost:5000}/api/end-user-public/<subdomain>/search	API_ENDPOINT (+ optional ADMIN_TOKEN)
"Ask a question" assistant	POST /_mintlify/api/search	${NEXT_PUBLIC_AI_MESSAGE_HOST}/api/end-user/search	NEXT_PUBLIC_AI_MESSAGE_HOST, NEXT_PUBLIC_TRIEVE_API_KEY

The self-hosted build sets none, so API_ENDPOINT falls back to http://localhost:5000 (nothing
there) and every query fails. (The original bug report's "404" was a wrong-path probe of
/api/search; the real routes are above and they 500.)

Change

• Dockerfile.docs — declare API_ENDPOINT, NEXT_PUBLIC_AI_MESSAGE_HOST,
  NEXT_PUBLIC_TRIEVE_API_KEY with empty (no-op) defaults. These are read at runtime by
  the standalone server, so real values belong in MangroveAI's Cloud Run env/secret; declaring
  them documents the contract and gives deploy an explicit override surface. Empty API_ENDPOINT
  keeps the built-in localhost fallback and Mintlify's env schema treats the empty NEXT_PUBLIC_*
  as undefined → behavior is identical to today (no regression).
• findings/docs-search-provisioning.md — exact root cause, live evidence, and the three
  resolution options with the env each needs.

Resolution options (the decision this draft unblocks — see #85)

1. Host docs on Mintlify's platform — search works out of the box (they index + provision).
   Cost: a Mintlify plan + DNS. Least code.
2. Keep self-hosting, provision Mintlify cloud search — index via Mintlify's API (CI step) and
   set the three env values at deploy time. Needs a Mintlify account/secret.
3. Self-hosted search, no Mintlify cloud — stand up a backend implementing
   POST /api/end-user-public/<subdomain>/search (Trieve-shaped) and point API_ENDPOINT at it,
   backed by a static index (Pagefind) or by Mangrove's existing free, no-auth
   https://kb.mangrovedeveloper.ai/api/search. Most consistent with self-hosting; most code.

Verification (real, throwaway containers — torn down after)

Built mangrove-docs-fix:verify from this branch's Dockerfile.docs and ran it.

1. Container is healthy; search is the only dead part (default config):

GET  /api-reference/overview                         -> HTTP 200   (docs render fine)
POST /_mintlify/api-public/search/docs               -> HTTP 500   (public box: backend absent)
POST /_mintlify/api/search                           -> HTTP 500   (assistant: backend absent)

This reproduces the bug through the real routes, and matches live prod:

POST https://docs.mangrovedeveloper.ai/_mintlify/api-public/search/docs  -> HTTP 500

2. The env lever works end-to-end — same real route, API_ENDPOINT pointed at a stub backend
on a shared docker network:

POST /_mintlify/api-public/search/docs   body={"query":"backtest strategy lifecycle"}
 -> HTTP 200
 -> {"stub_backend":true,"received_path":"/api/end-user-public/docs/search",
     "results":[{"title":"STUB RESULT — forwarding works",
                 "query_echo":"{\"query\":\"backtest strategy lifecycle\"}"}]}

# stub backend log (proves the docs route forwarded the query):
STUB RECEIVED: POST /api/end-user-public/docs/search  body=b'{"query":"backtest strategy lifecycle"}'

Honest scope: this proves the docs route forwards to whatever API_ENDPOINT points at — i.e.
the enablement lever is correct and wired. It does not prove real search results, because
that needs a real (Mintlify or self-hosted) backend with the docs content indexed — the product
decision in #85. Hence draft.

Refs #85 (not Fixes: merging this scaffolding alone does not resolve search).