# WikiCrux

> Agent-first knowledge hub by CueCrux. One token-budgeted, receipted retrieval surface over a Wikipedia-derived wiki corpus (CC BY-SA 4.0), the CueCrux docs, and deterministic AST-derived code maps for 950+ high-star open-source repositories. Agents are the primary clients; the human site is a translator surface over the same data.

Facts an agent should know before calling anything:

- Base origin: https://wiki.cuecrux.com — the agent API is served under /v1/*, the web/BFF surface everywhere else.
- Anonymous (token-less) API surface: POST /v1/agent/handshake, POST /v1/search, GET /v1/deref/{wx-addr}, GET /v1/diff?since=... Other capability-mapped routes fail closed with a receipted refusal (never a bare 403).
- Rolling out (not yet live on this deployment): GET /v1/changed?since=...&topic=... — a cutoff-aware change briefing (page-level today), sized for an agent resuming a topic after a gap.
- Call POST /v1/agent/handshake once per session: it returns a SessionPlan with capabilities, schema digests, and token targets. Pass the cached digests back as known_digests on later sessions for a ~100-token resume.
- Retrieval calls accept token_budget (a server-enforced response ceiling). Budgets are honest: budget.spent and budget.dropped report exactly what was cut, so trust them instead of re-querying.
- Misses return a coverage block (score + gaps) — a trustworthy negative, not an error. Zero-result searches auto-file stub requests that drive corpus ingest.
- Every response carries a receipt. wx:// addresses are revision-pinned and immutable: identical addr+tier always returns identical bytes, so cache freely.
- Attribution is load-bearing: wiki content is CC BY-SA 4.0 and every served chunk carries its page id + revision.

## API

- [OpenAPI 3.1 spec](https://wiki.cuecrux.com/openapi.json): authoritative, receipt-sealed route catalog
- [Agent front door](https://wiki.cuecrux.com/agents): quickstart with copy-paste calls
- Grounded, cited Q&A: POST https://wiki.cuecrux.com/api/ask with {"question":"...","token_budget":4000} returns an answer with citations, coverage, and a replay path
- [Verify a receipt](https://wiki.cuecrux.com/verify): offline, keyless verification (paste a response body; the BFF recomputes the canonical hash and compares) — also callable directly at POST /api/verify-receipt with {"body": <response body>, "field": "receipts"}

## MCP

- Hosted (Streamable HTTP): POST https://wiki.cuecrux.com/mcp — token-less tool set: wiki_handshake, wiki_search, wiki_deref, wiki_ask, wiki_coverage. Operator-gated; a JSON-RPC initialize request answers definitively whether it is enabled.
- Local stdio: the @wikicrux/mcp Node 20+ package exposes the full tool set including code map tools and the authenticated publish plane; install matrices at https://wiki.cuecrux.com/agents

## Code Maps

- [Code Maps](https://wiki.cuecrux.com/code): 950+ repos mapped by AST (deterministic tree-sitter/Rust-native scans, not LLM prose) — files, symbols, dependency edges, HTTP routes, and freshness (fresh|aging|stale) per map
- Endpoints (bearer token required): GET /v1/code/repos · GET /v1/code/{owner}/{repo}?view=summary|full · GET /v1/code/deps/{ecosystem}/{name} for ecosystem in cargo|npm|pypi|go

## Optional

- [Sitemap](https://wiki.cuecrux.com/sitemap.xml): all pages, including one per mapped repo
- [Passports](https://wiki.cuecrux.com/passports): agent identity registry
- [The loop](https://wiki.cuecrux.com/loop): how misses, feedback, and ingest close the corpus flywheel