# Koinar Biblical AI

**Scripture, retrieved. Never generated.**

A retrieval-grounded Bible study assistant built on the
[Model Context Protocol](https://modelcontextprotocol.io). Every verse the
assistant cites is retrieved from verified, checksummed databases — never
generated by a model. Extra-biblical background carries an explicit ⛰️ flag,
cross-references carry community vote counts, and every tool call is logged
under a named access key.

## Two ways to run it

- **Hosted** — the gated MCP endpoint at `https://koinar.app/mcp`
  (`Authorization: Bearer <key>`; keys are issued per named party).
- **Self-hosted** — churches run the full stack (MCP server + verified
  databases + a local Apache-2.0 model) on their own hardware with one
  command. Start at **[bundle/README.md](bundle/README.md)**.

## What's in this repo

| Path | What it is |
|---|---|
| `lib/mcp/` | The MCP server: 9 scripture-grounded tools, system prompt, key gating, audit log |
| `bundle/` | Self-host distribution: compose stack, Modelfile (Gemma 4 31B), install runbook |
| `Dockerfile.bundle` / `server-bundle.ts` | The lean self-host image (published to `ghcr.io/th3fifthestate/koinar-biblical-ai`) |
| `scripts/eval/` | The eval harness: rule-compliance, fabrication, boundary, and crisis-referral scenarios |
| `docs/` | Plain-language user guide |

## The trust invariant

The Bible lives in the database, not in the model. The model orchestrates
retrieval and formatting; it is never the source of scripture. This is the
product's founding constraint and it is non-negotiable in every tier —
hosted, self-hosted, and any future fine-tune (which would train *habits*,
never scripture content).