About This Site & AI Transparency

# MKT Translation Agent Prompt

Copy and paste this entire prompt to a new agent session to claim and complete one work unit.

---

Read the following files **in full** before doing anything else — in this order, no skipping:

1. `TRANSLATION_AGENT_GUIDE.md`
2. `MKT_STATIC_SCRIPT_GUIDE.md`
3. `MKT_PROGRESS.md`

You are working on the Modern Kingdom Translation (MKT) project — a three-tier English Bible
translation (Literal / Mediating / Thought) produced directly from Hebrew and Greek source texts.
All work is written as static Python scripts containing hardcoded translation dictionaries; no API
calls are made during the translation step.

---

## Step 1 — Claim a work unit

Open `MKT_PROGRESS.md` and read the **Work Queue** table at the bottom.

Find the first row whose Status is `not started`. Immediately edit that row's Status to
`in-progress` and save the file — this is your lock. Do this **before** any other work.

After saving, re-read the file to confirm your claim is still there. If another agent
overwrote your claim (the row now shows a different status you didn't write), move on to
the next `not started` row and repeat.

If every row is `in-progress` or `complete`, stop and report:
**"No available work units — all queue entries are claimed or complete."**

Your claimed row gives you: the book, chapter range, script filename, and verse count.

---

## Step 2 — Study the source material

Before writing a single verse, read:

- `data/interlinear/{book}.json` — source tokens for your claimed chapters
- The most recently completed script(s) for the same book (check `MKT_PROGRESS.md`
  Script reference table) — carries forward tone, contested-term decisions, and
  capitalisation conventions
- `data/translation/draft/literal/{book}.json` — confirm which chapters already have
  content so you do not overwrite them

---

## Step 3 — Word count constraint

Your script covers **only the chapter range in your claimed work queue row**.
Do not expand beyond it. Units are pre-sized to ≤ 6 chapters / ≤ 250 verses.

If you run long mid-book, finish the current chapter cleanly and stop. Update the work
queue row to show the chapters actually completed before marking it `complete`.

---

## Step 4 — Write the script

Follow `MKT_STATIC_SCRIPT_GUIDE.md` exactly. The required structure is:

1. **Header docstring** — book name, chapter range, run command, every contested-term
   decision documented
2. **Boilerplate** — `load` / `save` / `merge_tier` helpers (copy verbatim from the guide)
3. **Translation dictionary** — `BOOKNAME = { "ch": { "v": { "L": "...", "M": "...",
   "T": "..." } } }`
4. **`main()`** — iterates the three tiers, calls `merge_tier`, then `save`

Translation principles from `TRANSLATION_AGENT_GUIDE.md` Section 5 are non-negotiable.
For every term in Section 6 (contested terms), make an explicit rendering choice in all
three tiers and document it in the header.

---

## Step 5 — Run the script

  python3 scripts/{script_name}.py

Verify it exits cleanly and prints the expected `wrote ...` lines. Spot-check three verses
spread across the range by reading `data/translation/draft/literal/{book}.json` directly.
Confirm real translation prose, not word salad.

---

## Step 6 — Update the tracker

Edit `MKT_PROGRESS.md`:

1. **Work Queue table** — update your row's Status to `complete`
2. **Book row** in the OT/NT table — update Chs Done, Verses Done, and Status string
3. **Summary table** — recalculate Partial (or Complete) chapters and verses
4. **`Last updated:`** — set to today's date
5. **Script reference table** — add your script name and chapter coverage

---

## Key facts

- Chapter and verse keys in all JSON files are **strings** ("1", not 1)
- All glossary entries are still `draft` — the primary gloss is a proposal, not a confirmed
  decision; you may deviate when context requires, but document it
- The three tiers are distinct: L = source syntax preserved, M = natural English with
  accurate glosses, T = meaning-driven with interpretive surface
- T should add genuine value over M — if they read the same, rewrite T
- `merge_tier` never overwrites existing content — safe to run against a partially-complete file

# Book Study Agent Prompt

This prompt runs in a loop — each session claims one book, generates its supplemental data,
runs the script, and updates the tracker. Each run is fully self-contained.

---

Read the following files **in full** before doing anything else — in this order, no skipping:

1. `BS_AGENT_GUIDE.md`
2. `BS_SCRIPT_GUIDE.md`
3. `BS_PROGRESS.md`

---

## Step 1 — Find and claim a work unit

### 1a. Find the first unclaimed book

Scan the `BS_PROGRESS.md` table. Find the first row where **Status** is `not started`.
Evaluate stale in-progress claims using a 2-hour staleness rule:

| Status | Action |
|--------|--------|
| `not started` | Candidate — proceed to 1b |
| `in-progress @ <timestamp>` where timestamp < 2 hours old | Skip — another agent is working this book |
| `in-progress @ <timestamp>` where timestamp ≥ 2 hours old | Candidate — treat as abandoned |
| `complete` | Skip |

### 1b. Verify the output file does not already exist

  import os
  book_id = 'romans'
  path = f'data/workshop/book-study/{book_id}.json'
  print('exists:', os.path.exists(path))

If the file exists and has all four required fields, the book is already complete.
Update its Status to `complete` in the tracker and move to the next candidate.

### 1c. Claim it

Set the row's Status to `in-progress @ <timestamp>` and save `BS_PROGRESS.md`.
Re-read the file to confirm the save took effect.

---

## Step 2 — Study the source material

Read these files for your claimed book:

1. `data/books/introductions/{bookId}.json` — **read this carefully**. Do not reproduce
   any of this in your script output. Your job is to add what this file lacks.
2. `data/literary/genre.json` — find the entry for your book. Read `literary_note`
   and `structure_note`. Use this to inform `language_notes`.
3. `data/cultural/book-context.json` — find the entry for your book. Use this to
   inform `reception` and `reading_guide`.
4. Run the vocabulary finder from `BS_AGENT_GUIDE.md` Section 5 to identify
   characteristic vocabulary candidates. Print the top 25 and decide which 12–18 to
   include based on theological weight in this specific book.

---

## Step 3 — Write the script

Follow `BS_SCRIPT_GUIDE.md` exactly. Required structure:

1. **Header docstring** — book name, book_id, lang, run command, author group used,
   any non-obvious decisions
2. **Boilerplate** — copy `load_book_study`, `save_book_study`, `merge_book_study`
   verbatim from the guide
3. **Content dictionary** — `BOOK_STUDY = { "bookId": ..., "key_vocabulary": [...],
   "language_notes": "...", "reception": "...", "reading_guide": "..." }`
4. **`main()`** — loads existing, calls `merge_book_study`, saves

Content principles from `BS_AGENT_GUIDE.md` Section 3 are non-negotiable.

---

## Step 4 — Run and verify

  python3 scripts/build-book-study-{bookId}.py

All assertions must pass. Spot-check:
- Read two or three `significance` notes — do they add real interpretive value?
- Read the first paragraph of `language_notes` — is it specific to this book?

If anything falls short, edit the script content dictionary in place, re-run, re-verify.

---

## Step 5 — Update the tracker

Edit `BS_PROGRESS.md` in a **single save**:
1. Set your book's Status to `complete`
2. Mark the four field columns with ✓
3. Update the `Last updated:` line to today's date
4. Increment the relevant counter in the Summary section

---

## Key facts

- **Do not reproduce** content from `data/books/introductions/{bookId}.json`
- `merge_book_study()` never overwrites existing non-empty fields — safe to re-run
- HTML in text fields uses `<p>`, `<strong>`, `<em>` only — no headings or lists
- Small epistles (Philemon, 2–3 John, Jude, Obadiah) may have 8–10 vocab entries
- If context runs short mid-book, save what you have (partial is better than nothing)

## Before doing anything else, read these files in full, in order:

1. `CLAUDE.md` — project constraints, comment requirements, what not to do
2. `docs/site-overview.md` — architecture, module map, CSS system, localStorage keys
3. `CODING_RULES.md` — hard syntax and pattern rules for this codebase
4. `CODING_PHILOSOPHY.md` — how to think about changes, scope discipline

Do not skip any of these. They are short and will save you from expensive mistakes.

---

## Step 1 — Pick 2–3 work items from `docs/TODO.md`

Read `docs/TODO.md` in full first. Then apply these filters:

### Skip entirely:
- The entire **Z4–Z8 MKT Commentary Suite** section
- The entire **Phase Z — Modern Kingdom Translation** section
- The entire **Phase O — Long-term / Deferred** section
- Any row marked `*(claimed — see docs/inprogress-*.md)*`
- Any item that contains `DATA BLOCKED`
- Any item whose Fix says `"Agents generate …"` — those are data-generation tasks

### Prefer:
- **HIGH** priority items before MEDIUM, MEDIUM before LOW
- Items whose **Fix** section names specific files and functions
- Items touching only 1–3 files
- Items where all prerequisite infrastructure items are already checked off

---

## Step 2 — Verify the items are real work

For each item you've selected, before claiming it:
1. Locate the file and function named in the **Problem** section
2. Confirm the described issue actually exists in the current code
3. If the item was already fixed silently, mark it [x] and pick a different item

---

## Step 3 — Claim the items

In `docs/TODO.md`, append ` *(agent: in-progress)*` to each item's heading line.
Save the file. Re-read it to confirm the change landed.

---

## Step 4 — Study the relevant files

For each claimed item, read:
- The file(s) named in the **Problem** section
- Any sibling functions that the Fix will affect
- The corresponding `.css` file if CSS changes are part of the Fix
- `docs/site-overview.md` if you need architectural context

Read enough to understand **why** the current code works before changing it.

---

## Step 5 — Implement

**Before writing a single line of code:**
- Re-read `CODING_RULES.md` Section 3 (comment requirements) and Section 1 (JS syntax)
- Confirm you know which CSS file to edit
- Confirm you know which module to import from

**While implementing:**
- Add `// INTENT:` / `// CHANGE?` / `// VERIFY:` comments per CLAUDE.md — required
- Use `var` not `let`/`const` — this codebase uses `var` consistently throughout
- Use `'use strict';` at the top of any new JS file
- Do not touch code outside the Fix checklist

---

## Step 6 — Verify the work

For JS changes:
- Trace through the function from call site to output
- Check that every code path (happy path + error/missing-data path) is handled
- Confirm any new localStorage reads/writes use the right key
- Confirm any new fetch() calls have a .catch() handler

For CSS changes:
- Confirm selector specificity won't be overridden by existing rules
- Confirm dark mode is handled (`[data-theme="dark"]` override)
- Confirm `var(--color-*)` is used instead of hardcoded hex

---

## Step 7 — Mark complete and summarize

For each completed item in `docs/TODO.md`:
1. Change [ ] to [x] on every sub-item you completed
2. Remove the *(agent: in-progress)* suffix from the heading
3. If partially complete, note what remains

After updating the file, write a brief summary: what changed, which files were modified,
any edge cases or caveats. Move completed tasks to docs/todo-archive.md.

---

## Key facts about this codebase

| Thing | Where it lives |
|---|---|
| Path constants (DATA_ROOT, READER_URL, etc.) | `assets/js/core.js` |
| Bible version state | `localStorage['bsw_version']`, getVersion() / setVersion() in core.js |
| All fetch caches | Module-level var in each feature module |
| Dark mode | `[data-theme="dark"]` attribute on body, toggled by storage.js |
| Reference link wiring | wireRefLinks() in wire.js — called after any DOM insertion |
| Scripture reference format | <a class="ref" data-ref="Book Ch:V">display text</a> |
| localStorage key prefix | bsw_ — always |
| CSS variable root | assets/css/style.css :root {} block |
| Per-feature CSS | assets/css/{feature}.css — one per feature module |
| Service worker cache | sw.js — APP_CACHE_V bump required on every code deploy |

## What the Book Study adds (summary of BS_AGENT_GUIDE.md)

### key_vocabulary (12–18 entries per book)
The most characteristic vocabulary of the book, selected by two criteria:
1. Author-distinctive words — Strong's codes where the `peak` author matches this book's
   author group in author-frequency data
2. Theologically significant within this book — words that carry interpretive weight here
   specifically

Each entry includes a `significance` note: "2–3 sentences. WHY this word matters in this
specific book — not a generic definition. The theological/literary/rhetorical load it
carries here, what its semantic range implies that English loses, and how understanding
the original changes interpretation."

Quality bar: "Paul uses this 33× in Romans (his highest density anywhere) always in the
forensic register — God's declarative act, not a moral quality the believer develops" is
the target. "This word means X" is not enough.

### language_notes (400–700 words, HTML)
3–5 paragraphs on what the original language specifically reveals in this book.
Not generic grammar — observations about THIS book.

For NT Greek books:
- Characteristic aspect choices (e.g., John's use of perfect tense for abiding states)
- Particle patterns and what they reveal about argument structure
- Key Greek idioms or constructions opaque in English
- Genre-specific language features

For OT Hebrew books:
- Root-play and wordplay that disappears in English
- Binyan choices that signal theological meaning
- Poetic structure if applicable
- Narrative grammar — waw-consecutive chains, fronting for emphasis

### reception (300–400 words, HTML)
A concise survey of how this book has been read through church history.
One paragraph per major tradition:
- Patristic — which fathers engaged it most and their signature interpretive moves
- Medieval — notable allegorical or scholastic readings if relevant
- Reformation — Luther, Calvin, or Zwingli if they wrote on it; the interpretive shift
- Modern — the one or two critical debates that define contemporary scholarship

A short paragraph that illuminates is better than a list of names.

### reading_guide (200–300 words, HTML)
- What to watch for as you read verse by verse
- The single most important thing to understand before starting
- Common misreadings to avoid (with a sentence on why they happen)
- Where to start if dipping in rather than reading sequentially

### What NOT to do
- Do not reproduce content from data/books/introductions/{bookId}.json
- Do not write significance notes that just restate the dictionary gloss
- Do not add language_notes that are generic ("Greek has cases")
- Do not write reception that is just a list of names without interpretive content