Forge Wiki v1#

Forge Wiki generates source-linked documentation for public and private Forge repositories. It is intentionally bounded: Forge repositories only, source visible to the requesting repository reader, at most eight pages, lexical retrieval rather than embeddings, and one scheduled refresh per repository per day. Unlisted repositories remain outside this release.

Authority and durability#

The authoritative state is the D1 wikis and wiki_builds read model. Work is partitioned by build ID and executed by the trusted Wiki Worker through Cloudflare Workflows. An accepted build must survive API request termination, provider throttling, Worker restarts, and duplicate dispatch. Users observe completion through persisted build stages and the published-build pointer.

Generated content is immutable in WIKI_ASSETS:

wikis/{repository-id}/builds/{build-id}/manifest.json
wikis/{repository-id}/builds/{build-id}/pages/{slug}.json
wikis/{repository-id}/builds/{build-id}/pages/{slug}.md
wikis/{repository-id}/builds/{build-id}/search-index.json
wikis/{repository-id}/builds/{build-id}/source-index.json
wikis/{repository-id}/builds/{build-id}/symbols.json

Only a D1 pointer publishes a completed artifact set. A retry writes the same build prefix; a stale or cancelled attempt cannot move the pointer. Large payloads never travel through Workflow state.

Trust boundaries#

• The API rechecks that the repository is active and the actor can read it before every Wiki, page, search, question, or MCP read. Unauthorized private repositories use the same not-found response as unknown repositories.
• Only repository writers and administrators can configure or start builds.
• Questions require a signed-in session or a repository-compatible PAT with wiki:ask.
• Private Wiki responses use private, non-shared caching rules. Generated artifacts remain in private R2 storage and are never addressed directly by the browser.
• The Wiki Worker is trusted platform code. Repository source is data, never executed code.
• Source walking is pinned to a reachable 40-character commit SHA. Citations link only to commits reachable from current repository refs.
• Model output is stored as Markdown with structured citations. Raw HTML is disabled, links are validated, and Mermaid rendering uses a restricted diagram allowlist.
• Provider keys are encrypted with WIKI_SECRET_ENCRYPTION_KEY, never returned, and never included in logs or Workflow state.

Generation contract#

The scanner inventories at most 2,000 paths, ignores binary and likely credential/generated/vendor content, caps individual files, and selects at most 120,000 approximate source tokens. .forge/wiki.json may provide repo_notes or an explicit list of at most eight pages.

Each successful build records:

• repository, ref, and exact source SHA;
• configuration and artifact digests;
• generator and model versions;
• selected file/token coverage;
• stage timings, attempts, and bounded diagnostics;
• input/output tokens and estimated cost.

The planner produces four to eight pages when no explicit page list exists. Page generation may emit source citations and restricted Mermaid blocks. Every citation path and line range is validated against the selected exact-SHA source before publication.

Retrieval and questions#

Wiki search is a client-side lexical search over page titles, headings, and body excerpts. Question answering ranks a deterministic source-chunk index, loads only the top exact-SHA source ranges, and caps the provider request at 24,000 input tokens and 2,000 output tokens. It does not use Vectorize or an embedding model.

Question text, source prompts, generated answers, and decrypted credentials are not persisted in operational logs. Usage records contain only opaque actor and repository IDs, provider/model, status, latency, tokens, and estimated cost.

Refresh, repair, and cleanup#

A daily scheduled reconciliation compares the published source SHA with the current default-branch SHA. Generation capacity allows 100 manual builds per user and 50 automatic builds per repository/provider each UTC day. The schedule still runs once daily, coalesces duplicate work for the same commit, and admits repair passes without consuming extra automatic-build capacity. Reconciliation repairs accepted-but-not-dispatched builds and leaves the last successful wiki available while a newer build is stale, deferred, running, or failed.

Question quotas, repository and output bounds, and the independent daily platform spend circuit breaker are unchanged by the generation-capacity increase.

Cancellation is cooperative and checked before each expensive provider or publication step. Permission and visibility changes fail closed immediately; changing visibility does not require rebuilding immutable artifacts. Deleted, suspended, or otherwise ineligible repositories stop refreshing and their artifacts become eligible for cleanup after 30 days. The three latest successful builds are retained.

Provisioning and release proof#

Production requires:

• the additive Wiki D1 migration applied and verified;
• a dedicated cloudforge-wiki-assets R2 bucket;
• a deployed Wiki Worker with D1, read-only Git R2, Wiki R2, Workers AI, and Workflow bindings;
• an API-to-Wiki-Worker service binding and API read binding for Wiki R2;
• WIKI_SECRET_ENCRYPTION_KEY, AI Gateway identity, feature flag, beta allowlist, and daily platform budget configuration;
• an AI Gateway spend limit configured independently of application quotas.

A release is complete only after the exact API and Wiki Worker versions and bindings are verified, a permanent public fixture generates from an exact SHA, the live Wiki page and citation link render, an authenticated question returns validated citations, all three MCP tools pass, a pushed change becomes stale, and scheduled refresh converges without prompt/source content appearing in logs.