docs/README.md

# ControlMT documentation — the journey + the playbook

> A first-person record of building a 139M-parameter Kannada↔English translator from scratch, solo, on one consumer GPU, with an AI assistant as a collaborator. For ML engineers who want to build something similar.

This folder is six self-contained docs. Each one stands alone — read whichever match your interest, in any order. They cross-reference each other so you don't have to read all of them to learn one thing.

---

## Pick what you want to read

| If you want to … | Read this |
|---|---|
| **Get the highest-density version of everything I learned** | [`top-lessons.md`](top-lessons.md) — 10 lessons, one paragraph each |
| **Read the full chronological story (v1 → v2.3 public release)** | [`the-journey.md`](the-journey.md) — what I built, when, why, what surprised me |
| **Skip my mistakes — what I tried that didn't work** | [`what-didnt-work.md`](what-didnt-work.md) — 8 failed experiments + root-cause analysis |
| **Just the concrete recipes (no theory)** | [`how-it-was-built.md`](how-it-was-built.md) — data filtering, training schedule, eval, deployment |
| **Learn the AI-assistant collaboration patterns** | [`working-with-claude.md`](working-with-claude.md) — memory rules, background tasks, what to delegate |
| **Find anything in the repo** | [`repo-map.md`](repo-map.md) — folder layout + file conventions |

---

## Reading paths by use case

**"I have 10 minutes."**
Read [`top-lessons.md`](top-lessons.md). It's the synthesis. Each lesson links to the doc that explains it in depth.

**"I want to build a small specialized translation model."**
1. [`how-it-was-built.md`](how-it-was-built.md) — concrete pipeline
2. [`what-didnt-work.md`](what-didnt-work.md) — skip my dead ends
3. [`top-lessons.md`](top-lessons.md) — the higher-level patterns

**"I want to understand the journey + decisions."**
1. [`the-journey.md`](the-journey.md) — narrative
2. [`what-didnt-work.md`](what-didnt-work.md) — companion (the failures)
3. [`top-lessons.md`](top-lessons.md) — synthesis

**"I'm a solo developer using AI assistants and want to do this kind of work."**
1. [`working-with-claude.md`](working-with-claude.md) — the collaboration playbook
2. [`the-journey.md`](the-journey.md) — applied case study (this project)
3. [`top-lessons.md`](top-lessons.md) — synthesis

**"I'm trying to navigate the codebase."**
1. [`repo-map.md`](repo-map.md) — folder + file map
2. [`how-it-was-built.md`](how-it-was-built.md) — what each pipeline stage does
3. Then dive into the GitHub repo at [github.com/anandkaman/ControlMT](https://github.com/anandkaman/ControlMT) — the actual training scripts, model code, and pipeline live there

**"I'm interested specifically in the model itself, not the project around it."**
You probably want the public model card instead — [`../release/README.md`](../release/README.md) — which has the FLORES benchmark scores, intended use, limitations, citation info. Then come back here for the journey context.

---

## What's NOT in this folder

- **Live training instructions or hyperparameters** — those are in [`../TRAINING_GUIDE.md`](../TRAINING_GUIDE.md) (the public methodology doc)
- **Deployment recipes (CPU / GPU / Docker / SDK)** — those are in [`../release/DEPLOYMENT.md`](../release/DEPLOYMENT.md)
- **Strategic positioning vs competitors** — in my private working directory
- **Old design docs from earlier phases** — preserved in [`archive/`](archive/) (10 historical docs: original architecture, training-log-v1, dataset-migration plans, etc.). These are referenced from the new docs but kept frozen.

---

## A note on voice

These docs are written in first person, in my voice (Anand Kaman). I describe my decisions, my mistakes, what surprised me. That makes them more readable but also more vulnerable — I'm naming specific things I got wrong and what I'd do differently.

If you're an ML engineer with similar constraints (single GPU, solo, no funding), I hope the failures are at least as useful as the successes. The dead ends saved me weeks. Maybe this writeup saves you some.

---

## Found a problem with these docs?

The repo is public at [github.com/anandkaman/ControlMT](https://github.com/anandkaman/ControlMT). Open an issue or PR. The docs in this folder are versioned alongside the model itself — when v2.4 ships, I'll update the journey to extend through v2.4 and re-publish.