# mpm-technical-documents · MPM Documentation Kit

Write and build Message Point Media technical documents (TN, INS, SOP, BOM, SVY, TAP, DWG, TSB, PRO, SOW, WO) and Chinese editions for manufacturers, to the MPM Document Standard, from an MPM Documentation Kit folder.

**Version:** 1.3.0 (kit v1.3 = MPM Document Standard 1.3)
**Author:** Message Point Media · Technical Services (Jason Stedwell)
**Repo:** https://git2.mpm.to/mpm/mpm-documentation-kit
**CoWork Project:** CW-034 — MPM Documentation Kit

---

## Overview

The MPM Documentation Kit gives everyone at MPM the same way to produce technical documents: one standard, one build engine, one set of templates, and one Claude plugin that runs the workflow. Each document is a short Python script (`source/build.py`) that the `mpmdoc` engine renders to a branded US Letter PDF (11×17 for drawing sheets) through Playwright/Chromium. The engine handles everything mechanical:
- numbering and validation
- masthead, header and footer
- palette and embedded fonts
- figure and table numbering
- the revision-history block, anchored to the last page

Writers only supply content. The **mpm-technical-documents** plugin is skill-only: no MCP server and no credentials. It works on the user's local copy of the kit, connected to Claude as a folder. It reads the standard, sets up the project folder, writes the build script, builds the PDF (locally, or in Claude's cloud workspace when Python isn't available on the computer), checks every page, and files the result. Technical notes and drawings can also be issued as a **Simplified Chinese edition** for overseas manufacturers. It uses a master glossary and an embedded Chinese font, and the English edition governs.

---

## Skills

| Skill | What It Does |
|---|---|
| `mpm-technical-documents` | Creates, revises and builds MPM technical documents to the MPM Document Standard from a kit folder: technical notes (TN), installation guides (INS), procedures/SOPs, bills of materials (BOM), site surveys (SVY), technical action plans (TAP), drawing sheets (DWG), technical service bulletins (TSB, customer and internal editions), proposals (PRO), statements of work (SOW), field work orders (WO), and Simplified Chinese editions of TNs and drawings. Triggers include "write a TN", "make an install guide", "draw the mounting bracket", "rev the drawing", "service bulletin for", "proposal for", "SOW for", "work order for", "Chinese version for the factory", or any MPM document number such as `TN-LT-15R-01`. |

---

## Tools Reference

The plugin has no MCP tools; it drives the kit's build engine. These are the engine's building blocks, by area:

| Module | Components |
|---|---|
| **Document** (`mpmdoc.Doc`) | `section`, `sub`, `p`, `bullets`, `steps`, `table` (`KeyRow`, `TotalRow`), `figure`, `calc`, `note` (info/warn/ok/verify), `kpis`, `result`, `dark`, `before_you_start`, `two`, `assumptions`, `signoff`, `approval`, `glance`, `step`, `shot`/`shots`, `special`, `chain`, `checklist`, `kv`, `part`, `photo`/`photos`, `transcript`, `bom` |
| **Commercial & field** | `parties`, `priced` (computed totals → `price_total`), `milestones` (fails the build if milestones ≠ price), `pill`, `fields` (fill-in records), `signatures`, `money` |
| **Drawing sheets** (`mpmdoc.Drawing`) | `view`, `sheet` (11×17 with title block, schedule, general notes, zones) |
| **Figures** (`mpmdoc.figkit`) | `svg_open`, `dim_h`, `dim_v`, `tag`, `T`, palette constants |
| **Units** (`mpmdoc.units`) | `ftin`, `inch`, `mm_in`, `signed`, `show_date` |
| **Chinese editions** (`mpmdoc.i18n`) | `Doc/Drawing(lang="zh")`, `Translator` (document terms → master glossary; `check()` fails on untranslated figure text), `governing_note` |

**Document types and templates** (`_STANDARDS/templates/<TYPE>/`): TN, INS, SOP, BOM, SVY, TAP, DWG, TSB, PRO, SOW, WO. TN and DWG also have `build_zh.py` for the Chinese edition.

---

## Setup Instructions

Full guide: `START_HERE.md` in the kit.

**Step-by-step:**
1. Get the kit: download `MPM-Documentation-Kit_v1.3.zip` from the CW-034 Drive folder. It includes worked examples; this repo holds the same kit without the customer examples. Unzip it somewhere permanent, e.g. `Documents/MPM Documentation/`.
2. Install the build tools:
   - **Mac/Linux:** run `./setup.sh` in the kit folder. It installs the Python packages and Chromium, and poppler via Homebrew/apt.
   - **Windows:** install Python 3.10+ and poppler, then run `py -m pip install -r requirements.txt` and `py -m playwright install chromium`.
3. Install the plugin: drag `_PLUGIN/mpm-technical-documents.plugin` into a Claude chat and accept it.
4. Give Claude the kit folder: open a Cowork task on it, or link the computer that holds it.
5. Verify: ask Claude to "rebuild the CommTran TN example", or run `python3 build.py` in `_EXAMPLES/COMMTRAN PINGO P2.5/source`.

### Setup Checklist
- [ ] Kit unzipped to a permanent folder
- [ ] `setup.sh` run (or the Windows commands)
- [ ] `pdftotext` available (poppler)
- [ ] Plugin installed in Claude
- [ ] Kit folder connected to Claude
- [ ] Example rebuilt successfully

---

## Connection Details

| Field | Value |
|---|---|
| Server | None: skill-only plugin, no MCP server, no credentials |
| Works on | The user's local kit folder (connected folder in Claude) |
| Build runtime | Python 3.10+, Playwright/Chromium, fontTools, brotli, Pillow, poppler (`pdftotext`) |
| Fallback | Claude's cloud workspace builds when the computer can't, writing results back to the folder |
| Number registry | Shared master registry (location set by MPM Technical Services); the kit's `registry.md` is a snapshot |

---

## Workflow Notes

- **Numbers:** `TYPE-CUST-SUBJ-NN`, claimed in the shared master registry before the first build, never reused. New customer codes also go into `mpmdoc/brand.py`.
- **Revisions:** 0.x = draft, 1.0 = first release. Any change after a document is shared gets a new revision and a history line. Old PDFs move to `_superseded/`; originals live untouched in `_INPUTS/`.
- **Sourcing:** every number traces to a source, and anything unconfirmed is TBC plus an open item. Proposal and SOW prices come line by line from the quotation; totals are computed by the engine.
- **TSB:** one script builds a customer edition and an internal edition (Part 2: diagnostic detail).
- **PRO and WO:** a PRO is marked Confidential and a WO Internal.
- **Chinese editions (TN, DWG):**
  - `build_zh.py` sits next to `build.py`; build the English first, since the engine refuses otherwise.
  - Body text is in Chinese, with bilingual frame labels and dimensions mm first.
  - Terms come from `_STANDARDS/glossary_zh.md`, one English term to one Chinese term. Manufacturer corrections go into the glossary.
- **Checks before issue:**
  - every page rendered and looked at
  - no build markers left in the PDF
  - a stable page count across two builds
  - classification correct
- **The kit is generated:** the master project produces it with `_STANDARDS/package/make_mpm_kit.py`. Don't edit the engine or templates in a user's copy; changes ship as a new kit version.

---

## Requirements

- Python 3.10+ — https://www.python.org/downloads/
- Playwright for Python + Chromium — `pip install playwright && python3 -m playwright install chromium`
- fontTools, brotli, Pillow — `pip install -r requirements.txt`
- poppler (`pdftotext`) — `brew install poppler` / `apt install poppler-utils` / Windows binaries
- Claude desktop app with folder access (Cowork) for the plugin workflow

---

## Troubleshooting

| Symptom | Fix |
|---|---|
| `ModuleNotFoundError: playwright` or `Executable doesn't exist` | Run `setup.sh` (or `python3 -m playwright install chromium`). |
| Warning: `poppler's pdftotext not found` | Install poppler; without it, the revision block isn't anchored to the page bottom. |
| `ModuleNotFoundError: figs` | Run `python3 build.py` from inside the `source/` folder, not with `python3 -I`. |
| `unknown customer code` | Add the code to `mpmdoc/brand.py → CUSTOMERS` and to the shared registry. |
| `Build the English edition first` | Run `build.py` before `build_zh.py`; both must use the same number, slug and revision. |
| `Untranslated text …` | Add the listed strings to the document's `TERMS` or to `glossary_zh.md`. |
| `milestones total … != priced total` | Fix the SOW milestone amounts so they add up to the quotation total. |
| Claude says no kit folder is connected | Open a Cowork task on the kit folder, or link the computer that holds it. |

---

## Related CoWork projects

- **CW-001 MPM Brand Voice:** the source of the kit's MPM fonts and logos.
- **CW-021 TSB MPM Skill and CW-011 MPM SOW Drafter:** these overlap with the kit's TSB and SOW types, to be reconciled with their owner.