RFC: build once, serve everywhere with Pages and artifact-backed MCP

[fishmingyu]

Summary

Make CodeNib a build-once, serve-everywhere repository-context platform. One commit-addressed artifact should support a public static Wiki, local or team MCP clients, and agent integrations without rebuilding the repository or leaking provider credentials.

This RFC extends the completed local Developer Preview in docs/product_roadmap.md. It does not replace the manifest-backed compiler/runtime or introduce a hosted SaaS.

Motivation

CodeNib already provides incremental multi-view indexing, source-linked Wiki pages, MCP tools, and agent-native repository exploration. The missing product layer is distribution:

• a public repository cannot deploy a CodeNib Wiki with one reusable GitHub workflow;
• the current Wiki requires a live API and cannot be published as a secret-free Pages artifact;
• local and BYO inference routes do not share an explicit user-facing compatibility contract;
• local MCP clients cannot reuse the exact artifact built in CI;
• token and USD reports are not yet tied to a quality criterion.

The product thesis is: build repository context once, then reuse the same provenance-checked artifact across human and agent surfaces.

Product Contracts

Static surface

A static export contains only publishable repository-derived data and generated prose. It must work without a server or browser-side secret. The baseline serves precomputed Wiki pages, source citations and navigation, and dependency views when available. It does not execute BM25 or dense retrieval in the browser; those query capabilities belong to the matching context artifact when loaded by a local or MCP runtime.

Remote semantic generation or embedding is a build-time capability. Query-time semantic Ask remains a local/authenticated runtime capability until a safe execution boundary exists.

Provider surface

The default GitHub Action uses no inference credential: it builds deterministic Wiki content and BM25. Optional local Hugging Face or BYO OpenAI-compatible routes may add semantic vectors and generated prose. Provider, model, endpoint identity, dimensions, prompt version, and pricing snapshot are recorded without secrets.

GitHub Models was fully retired by GitHub on 2026-07-30 and is not a CodeNib runtime dependency.

Artifact surface

Every export identifies repository, commit, schema, builder/profile, source-address contract, view capabilities, and generation provenance. Static Wiki and MCP consumers reject incompatible artifacts instead of silently rebuilding or serving stale data.

Cost surface

The primary experimental metric is cost per successfully localized query, not cost per resolved issue. Reports pair localization quality with model-call cost and optional amortized build cost. Raw token classes and pricing provenance remain explicit; Copilot AI Credits are not inferred from model tokens.

Security and Non-goals

• Never expose Action secrets or provider credentials in Pages output.
• Do not run secret-bearing generation on untrusted fork code or pull_request_target.
• Public static mode degrades deterministically when optional providers are unavailable.
• This RFC does not promise browser-only semantic inference, a hosted backend, patch correctness, lower Copilot AI Credit usage, or a universal retrieval route.
• Enterprise multi-version storage remains tracked independently in RFC: Enterprise index storage — three orthogonal axes (version / snapshot / tenancy), git-content-addressed graph #199.

Implementation Plan

• M1: Static artifact contract. Add deterministic Wiki export, provenance schema, static frontend data adapter, Pages base-path support, secret scan, and browser smoke tests.
• M2: Local and BYO providers. Add explicit chat/embedding configuration, compatibility fingerprints, doctor checks, and secret-safe behavior.
• M3: GitHub Action and Pages. Restore/update incremental state, publish a commit-addressed artifact and static site, support no-model fallback, and document permissions/budgets.
• M4: Artifact-backed MCP. Fetch and verify a compatible artifact by commit, bind it to an exact checkout, and preserve compact citation-first tool responses.
• M5: Cost-quality evaluation. Report localization success, attempted-query cost, successful-localization cost, cached/uncached token units, and build amortization at fixed query counts.
• M6: Release acceptance.

[fishmingyu]

H1 is implemented and ready for review in #418; the durable H1-H6 roadmap is in #417. The static export now provides the first commit-addressed, secret-free serving artifact and deliberately exposes only serverless capabilities. Remote checks are queued; H2 provider-contract work can proceed independently from main while H1 is reviewed.