# 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`:

```text
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.