# Ask Ultimate Macro Wiki

**Status: live in production.** Default sourced mode returns extractive answers from published guides; the static Markdown/compact-index fallback remains available.

## One question, one HTTP request

Endpoint: POST https://ultmacro.xyz/api/wiki/v1/ask

Request (JSON, maximum 2 KiB total, required question of 3–300 characters):

    {"question":"Why won't my towers upgrade?","version":"v1.3.5"}

Optional fields: version (a release filter like v1.3.5 or v1.3.x), mode ("sourced" by default or "ai"). Set Content-Type: application/json. No API key is needed for default sourced answers. Never embed provider keys in a Discord bot or downloadable package.

Example from a shell:

    curl -sS -X POST 'https://ultmacro.xyz/api/wiki/v1/ask' \
      -H 'Content-Type: application/json' \
      --data '{"question":"How do I record a strategy?"}'

Typical result shape (illustrative, not copied from a live response):

    {
      "status": "answered",
      "answer": "1. Open Create → Record a Strategy.\n2. ...",
      "answer_type": "extractive",
      "citations": [{
        "slug": "record-strategy",
        "title": "Record a strategy",
        "section": "Record and save",
        "url": "https://ultmacro.xyz/wiki/?article=record-strategy",
        "source": "/guide/recording/",
        "version": "v1.3.x"
      }],
      "version": "v1.3.x",
      "source_scope": "published_documentation",
      "ai_used": false,
      "cache": "miss"
    }

If evidence is insufficient: HTTP 200 with status "not_found", answer null, citations [], a reason, and up to three related **published** guide links. Clients MUST check status before displaying answer and must not represent related reading as a proven solution. Invalid requests return HTTP 400, 413 or 415 with an error body.

Every answer and citation is drawn from the existing **127 published source-linked guides** only. The separate **778 unverified candidate topics are excluded**. Results are about documented releases, not proof that the fix works on an individual device. Release filters never silently promote old documentation to a new version.

## Developer integration

- [JavaScript helper](../examples/ask-javascript.mjs): import askWiki(question) into a Node 20+, web or Discord backend; no npm SDK dependency.
- [Python helper](../examples/ask.py): stdlib-only ask_wiki(question), no pip dependency.
- [Discord.js v14 command adapter](../examples/discord-ask.mjs): defer the interaction, call Wiki Ask, show a sourced embed and handle no-answer cases.
- [AI tool adapter](../examples/ai-tool.mjs): provider-neutral tool definition and handler, reusing the same Wiki backend.
- Existing /api/wiki/v1/search and /context remain available for systems that want excerpts rather than an answer.

The JavaScript and Python helpers use POST even for short questions. This avoids question text in URLs, browser history and typical proxy access logs. They are source examples in the repository, **not published packages**.

## Answer quality and control

- Search and rank sections (not only article titles), with targeted aliases for familiar troubleshooting terms.
- Prefer the exact guide, sections with applicable steps, and troubleshooting guides for problem reports.
- Expose the excerpt **directly from the source** in default mode. This is not prose generated by a model.
- Avoid misleading low-relevance "answers": return not_found with related reading instead.
- Source citations always include title, section, official Wiki URL, release version and original source.
- Cache repeated questions in memory for five minutes, with a maximum of 120 entries per Node process. Responses use Cache-Control: no-store to avoid caching an individual question at intermediate public layers.
- Limit request body to 2 KiB at the Node server and Ask handler; reject unexpected JSON keys and bad version syntax.

## Optional AI synthesis

Default is **off**. Sourced mode uses zero provider calls. To enable provider-side composition, an operator must configure all four trusted server-side settings:

    WIKI_ASK_AI_ENABLED=1
    WIKI_ASK_AI_URL=https://your-trusted-provider.example/v1/chat/completions
    WIKI_ASK_AI_MODEL=operator-chosen-model
    WIKI_ASK_AI_KEY=<server-only-secret>

The endpoint must be HTTPS. Never use arbitrary client-supplied provider URLs or keys. Model request is restricted to at most three source excerpts, max_tokens 240, 4.5-second timeout and a maximum 32 KiB response. The server defaults to 30 provider calls per hour per Node process and two concurrent calls, plus a bounded in-memory result cache. These are **best-effort process-local budgets**, not global per-user rate limits. Deployments with multiple replicas need centralized budgets and abuse/rate limiting at the trusted edge before opening this to public AI traffic.

Only mode "ai" asks for synthesis, and only after strong source retrieval. Failure, timeout, refusal, budget exhaustion or an invalid model response returns the original source excerpt, with an ai_status reason. AI output is marked answer_type "ai_draft" and is **not claimed to be a mechanically verified fact**. Citation links refer to the supplied source sections; a model can still make synthesis mistakes.

Do not enable public provider spending before the API route is confirmed, the quota is funded and edge-side rate limits are configured. There is no client-side API secret and no "free unlimited AI" claim.

## Should there be an MCP server?

Not yet. A minimal MCP adapter could reuse the live askWiki(question) call later, but introducing a separate server would increase hosting and maintenance burden. Stabilize REST and bot integrations first.

## Deploy verification

See [DEPLOYMENT.md](./DEPLOYMENT.md) and the read-only deployment checker from PR #41, which diagnose local, origin and public Wiki API failures. The static index and per-article Markdown are already live. Run npm test, then confirm:

- POST /api/wiki/v1/ask with a real upgrade question returns status answered, correct section and sources.
- POST with an unknown or unreleased-version question returns status not_found, not an invented answer.
- GET /api/wiki/v1/ask returns 405; OPTIONS advertises Content-Type.
- Oversized/malformed POST requests are rejected and existing GET search/context continue to work.
- No provider calls occur with AI disabled.
- The response functions from the public domain, not merely localhost.

Production verification completed against localhost, api-origin.ultmacro.xyz and ultmacro.xyz. Re-run the deployment checker after future backend or proxy changes.