The BNLRepo mirror model

Everything else in BNLGit is a consequence of one naming rule.

The pairing

A BNLRepo pairs an ordinary source repository with a second, generated repository that holds nothing but summaries.

A repository whose own name ends in -llm cannot be paired — that suffix is reserved so the pairing is never ambiguous.

What is in a summary file

Each .llm file carries front matter pinning its provenance: the source repo, ref, commit SHA, blob SHA, path and line count, the model and route used, the credential reference, the prompt version, and the generation time. A cloned mirror is therefore auditable on its own, with no database lookup and no access to our servers.

Below the front matter is a readable Markdown summary, and — for the current schema, bnlgit-summary-v3 — a block of typed facts:

• sections — prose claims, each with a declared kind: purpose, key symbols, inputs and outputs, data flow, side effects, dependencies, errors and edge cases, security, change-sensitive areas.
• symbols — name, kind, role.
• imports — module, imported names, dependency kind.
• api_endpoints — method, path, handler symbol, auth, inputs, outputs.
• database_entities — name, kind, operation, detail.
• side_effects — kind, target, operation, detail.
• security_concerns — kind, severity, detail.
• related_files — path, relationship, reason.

Every statement and every structured fact carries one or more 1-based source line spans. Those spans are re-validated against the pinned blob's real line count when a summary is read, so a fact cannot silently point outside the file it describes.

Summaries written under the older bnlgit-summary-v2 schema remain trusted and searchable, but do not carry the structured fact block — they are not graph-ready until regenerated.

Creating a BNLRepo

From a repository page, use the BNLGit pairing action, or call the API:

POST /api/v1/repos/{owner}/{repo}/bnlgit/pair
Authorization: token <your token>
Content-Type: application/json

{
  "llm_credential_ref": "openrouter-primary",
  "llm_model": "anthropic/claude-sonnet-5"
}

The credential reference and model are required and explicit — BNLGit never infers a BYOK connection or picks a default model for you. If you have not saved a connection yet, start at BYOK connections.

If a pair ends up in a bad state — for example the mirror repository was deleted out from under it — POST /api/v1/repos/{owner}/{repo}/bnlgit/repair fixes the pairing without losing its history.

Generating summaries

Pairing generates nothing by itself. BNLGit only spends your provider tokens when you ask it to.

Open the repository's BNLRepo Sync Cockpit at /{owner}/{repo}/bnlgit to see every file's state:

A source change always raises needs_regeneration. By default — auto-regenerate is off per BNLRepo — nothing is claimed for work until a human presses Generate, which sets a separate regeneration_requested flag. A flag can be dismissed instead, which records who dismissed it and when, without pretending the old summary became current.

The drift signal

Every BNLRepo status response and the sync cockpit surface a single green / yellow / red badge, always shown together with the verified-current percentage and the reasons behind the colour:

• 🟢 Green — at least 90% verified-current, zero stale, unverified or failed summaries, and no high-risk cleanup findings.
• 🟡 Yellow — at least 70% verified-current and no high-risk findings. Some drift remains.
• 🔴 Red — under 70% verified-current, or any failed summary, or any high-risk cleanup finding.

Those thresholds are not marketing copy; they are returned by the capabilities endpoint so a script can read them rather than hard-code them.

File view

A source / summary / split toggle on any file view lets you jump between a source file and its .llm twin, in either direction.