<!--
Drafted directly into the demo repo (not yet mirrored from the engine repo).
Source of truth will move to dinukxx/Machineworld at docs/use/scenarios/dhamma-reference.md
on the next engine release. Edits here will be overwritten then.
-->

# Dhamma reference — grounded, never generated

*A programmable Process scenario — 2 of 15.*

> *Families at home — in any quiet room with a phone or a laptop — can have
> accurate, sourced Dhamma conversations in Sinhala, Pāli, and English. Fully
> offline if they wish. Every doctrinal answer carries the verifiable passage it
> came from. The model handles language; doctrine is retrieved, not generated.*

---

## What a Tuesday evening looks like

A grandmother in Galle, sitting with her grandson over school holidays, asks:
*"What did the Buddha actually say about anger?"* She speaks Sinhala. The boy
prefers English. Neither of them wants a chatbot opinion. They want the passage.

```
Question — sourced answer
✓  Akkosa Sutta (SN 7.2) · Saṃyutta Nikāya
   Sinhala (BJT)  ·  Pāli (BJT)  ·  English (SuttaCentral, Bhikkhu Bodhi tr.)
   Source: tipitaka.lk · Path Nirvana Foundation · CC BY-ND
   Auto-sync on : last corrections pulled 2 days ago
ⓘ  Related: Kakacūpama Sutta (MN 21), Cūḷahatthipadopama (MN 27)
·  Abhidhamma framing — dosa cetasika · Aṭṭhasālinī §III.5
   Source: pitaka.lk · Ven. Rerukane Chandawimala Thero · permission pending
!  Tap to hear in Sinhala (offline TTS)             [play]
```

Three citations. Zero generated doctrine. The model produced the conversation
that surrounded the passage — *"the question your grandson is asking is the same
one a brāhmaṇa once asked the Buddha"* — but every sentence carrying meaning
about the Dhamma is a quoted passage with a path back to its source.

---

## What this Process actually does

This is a Process — composed of skills, governed by the same actor contract that
runs every other Machine World Process — but its shape is worth seeing on its
own, because **a Dhamma reference is the case where hallucination is unacceptable.**

| Step | Actor class | What happens |
|---|---|---|
| **1. Intent** | Human (you) + intent-extractor skill | Question understood in Sinhala / Pāli / English. Doctrinal vs personal-application distinction made explicit. |
| **2. Retrieve** | Digital — retrieval skill | The relevant Tipiṭaka passage(s) are pulled from the canon. Sutta, Vinaya, Abhidhamma, Paṭṭhāna are all in scope. Nothing is paraphrased. |
| **3. Cite** | Digital — citation skill | Every quoted passage is shown with publisher, license, last-sync date, and a deep link back. The reader can verify before they trust. |
| **4. Frame** | Digital — language model (Gemma fine-tune) | The model surrounds the citation with the question's context. The model does the *language*. It does not do the *doctrine*. |
| **5. Vinaya gate** | Digital — vinaya skill | The framing is checked for lobha, dosa, moha before it reaches the reader. Anything that would manipulate, agitate, or mislead is rewritten or held. |
| **6. Gap → request** | Human — project-owner actor | If a passage is missing, mistranslated, or behind a non-open license, the Process opens a *digitization / correction request* to the project owner — tipitaka.lk, pitaka.lk, SuttaCentral — and tracks it like any other actor-contract task. |

Step 6 is the part that makes this a Process and not a search bar: **the canon
itself is a living, multi-decade community effort, and Machine World is built to
participate as a respectful downstream user — sending corrections back upstream,
not forking silently.**

---

## Who the human actors are (and what their contracts say)

| Actor | Their contribution | What MW commits to in return |
|---|---|---|
| **Path Nirvana Foundation · tipitaka.lk** | The cleanest digitization of the Sinhala-Pāli canon in existence. CC BY-ND. | Verbatim quotation with credit on every use. Automated upstream-sync so corrections you publish flow to every MW user. Permission asked before any training use. |
| **Ven. Rerukane Chandawimala Thero's works · pitaka.lk** | Sinhala-language Abhidhamma and Paṭṭhāna scholarship. | Quotation only after permission is granted by the rights-holder. Until then, references stay marked "permission pending" and are not shown by default. |
| **SuttaCentral** | English translations (Bhikkhu Bodhi, Bhikkhu Sujato, others) under open licenses. | License-compliant attribution, contribution of corrections, no derivative claims. |
| **arutha.lk** | Sinhala dictionaries and lexical resources. | Optional integration for word-level glosses, with credit. Pending the team's interest. |
| **Bhikkhus, bhikkhunīs, upāsakas, upāsikās** | Lived practice; correction; the question of *what counts as accurate*. | Every released artifact credits the people who shaped it. The doctrine is theirs, not Machine World's. |

This is the same six-field actor contract that runs the [caregiver scenario](/machine-world/caregiver) —
identity, capabilities, availability, constraints, rate, SLA. The shape is
universal precisely because the participants are not. A canon-digitization
foundation and a helper in Colombo participate under the same architectural
contract, with the same right to surface gaps and be paid (in attribution, in
upstream-sync, in token credits) when the work they did is invoked.

---

## The model story (what the LLM is, and what it is not)

A small open model — **Gemma, Apache 2.0** — is being fine-tuned so that
ordinary phones can understand and express **Sinhala, Pāli, and English** well
enough to hold the surrounding conversation. The fine-tune happens on
language-only signal: structure, register, classical vocabulary, code-mixing.

What the fine-tune is *not* doing:

- It is **not** memorising sutta passages so it can recite them. That is the
  retrieval system's job, against verifiable sources, with citation.
- It is **not** absorbing doctrinal interpretation as latent weights. Doctrine
  stays in the canon, not in the model.
- It is **not** trained on closed sources without permission. Training use of
  any CC BY-ND text waits on the rights-holder's word.

When the local-offline build ships with the mw CLI, every phone, every
laptop, every quiet corner can hold this conversation without sending a single
word to a server. **A family asking a Dhamma question is not an internet
transaction.**

---

## Why this is the right Process to build

Machine World exists to **return your attention to you**. The classical
framing for that is *viveka* — seclusion. *Kāya-viveka* is bodily seclusion;
*citta-viveka* is mental seclusion; *upadhi-viveka* is the seclusion that ends
suffering at its root. Modern digital life makes even kāya-viveka and
citta-viveka harder than they should be: the body sits down, but the mind
doesn't stop being pulled.

The first thing Machine World does is hold the small stuff so the day can quiet
down. The Dhamma-reference Process is the second thing: when the quiet day
turns toward a real question, the answer arrives with its source, in your
language, without an opinion grafted on top.

---

## What it is not

- **Not a teacher.** It does not interpret. It does not rank teachers. It does
  not have an opinion about your sīla or your samādhi.
- **Not an oracle.** It can fail, and it knows how to say *"this passage is not
  in our canon yet; a request has been opened with the maintainers."*
- **Not closed.** Every line of the retrieval, citation, vinaya, and framing
  skills is open-source. Every source is credited. Every correction can be sent
  back upstream.
- **Not free of its license obligations.** CC BY-ND means BY-ND. The auto-sync
  is built. Permission for training is asked, not assumed.

---

## Acknowledgements

This Process exists because of the people who spent years digitizing the canon
when no one was paying them to. Path Nirvana Foundation, the team behind
pitaka.lk, Ven. Rerukane Chandawimala Thero's lineage, SuttaCentral, the
arutha.lk team, and every bhikkhu, bhikkhunī, upāsaka, and upāsikā who has ever
corrected a transcription — Machine World stands downstream of your work, and
will keep crediting it for as long as the system runs.

If you are one of those people and you would like to talk about how Machine
World refers to your work, the door is open: **margasaakachcha@gmail.com**.

— *With mettā, Gehan Panapitiya*
