mpm-documentation-kit/_STANDARDS/MPM_Document_Standard.md

MPM Document Standard

Version 1.3 · Released · Nov 9, 2026 · Owner: Jason Stedwell

This is the rule set for every technical document produced in the DOCUMENTATION PROJECT. It covers what each document type is for, how it is numbered, named and filed, how it looks, and how it reads. The engine in mpmdoc/ enforces the mechanical parts (numbering, masthead, header/footer, palette, revision history); this document covers the judgement parts.

MPM Documentation Kit edition. Everything in the kit is Message Point Media. Replace your kit when MPM Technical Services releases a new version; the version line above tells you which one you have.

---

1. Document types

Code	Type	Use it when	Audience	Default marking	Length	Template
INS	Installation Guide	Someone has to physically install hardware, step by step	Customer facilities, installers, MPM field	Customer	4–10 pp	Ready · templates/INS/
SOP	Standard Operating Procedure	A repeatable internal task (setup, onboarding, process)	MPM staff	Internal	2–6 pp	Ready · templates/SOP/
TN	Technical Note	One engineering question needs a worked, checkable answer	Customer + MPM engineering	Customer	1–3 pp	Ready · templates/TN/
BOM	Bill of Materials	Pull, check and pack a set of parts	MPM shop / field	Internal	1–2 pp	Ready · templates/BOM/
SVY	Site Survey	Recording what was found on site and what it means for design	Part 1 customer, Part 2 MPM-internal	Customer	4–12 pp	Ready · templates/SVY/
TAP	Technical Action Plan	A planned engagement: scope, staffing, logistics, success criteria	Customer / OEM partner	Confidential	5–12 pp	Ready · templates/TAP/
DWG	Drawing sheet (11×17)	Mechanical, cable, mounting or fit-out drawings with title block	Fabrication, customer approval	Customer	1–4 sheets	Ready · templates/DWG/
TSB	Technical Service Bulletin	A known product issue and its fix for every affected unit	Customer edition: agencies, partners · Internal edition: MPM field and support	Customer (internal edition: Internal)	2–5 pp	Ready · templates/TSB/
PRO	Proposal	Before award: need, proposed solution, why MPM, investment	Agency / partner decision makers	Confidential	3–8 pp	Ready · templates/PRO/
SOW	Statement of Work	After award: contractual scope, deliverables, milestones	Customer / partner, under the MSA	Customer	2–6 pp	Ready · templates/SOW/
WO	Field Work Order	Dispatching one job at one site to an MPM tech or a subcontract installer	Technician / installer, site contact	Internal	1–3 pp	Ready · templates/WO/

Also standard but not a PDF: 00_INDEX.md, a project index (see §4.3).

New types are assessed when they come up; don't improvise a code. Add it to brand.TYPES and this table first.

Picking the type:

• Steps someone performs → INS (outside MPM) or SOP (inside MPM).
• A number, a fit or a yes/no with working → TN.
• A list of parts → BOM.
• A record of what exists on site → SVY.
• A plan for a visit or engagement → TAP.
• Geometry someone will fabricate from → DWG.
• A product defect and its fix across units → TSB. (One site's one-off problem is a TN or a TAP.)
• Winning the work → PRO. Defining the awarded work → SOW. A PRO never turns into the SOW; the SOW gets its own number.
• Sending someone to do one job → WO. How to do the job is the INS it references.

---

2. Brand selection

• MPM (gold/ink, Montserrat + Open Sans + JetBrains Mono) is used for every document.

---

3. Numbering

3.1 Format: TYPE-CUST-SUBJ-NN

Field	Rule	Examples
TYPE	Code from §1	INS, TN, BOM
CUST	2–4 letters: customer code, or MPM department for internal docs (IT, ENG, OPS, QA), or MPM for company-wide/product docs	LT, NSH, CMT, OMT, SOR, GIL
SUBJ	2–8 letters/digits naming the subject: site, product, bay, kit, job	15R, B17, P25, HW, UNIFI, MON
NN	Two-digit sequence within TYPE-CUST-SUBJ, starting 01	01, 02

• Uppercase, hyphens only, no spaces.
• A number is issued once and never reused, even if the document is abandoned.
• A new subject on the same project gets a new SUBJ. A second document of the same type on the same subject gets the next NN.
• Register the customer code and the number in registry.md before the first build. The engine refuses unknown customer codes.
• TSB: MPM + product family for a product-wide bulletin (TSB-MPM-LX270-01); a customer code only when the issue belongs to one deployment.
• PRO / SOW: the customer the document is addressed to (the partner when MPM works through one, e.g. Vontas), SUBJ = project. A SOW that follows a PRO keeps the same SUBJ.
• WO: the customer code of the job, SUBJ = site or job; one WO per dispatch.

3.2 Existing documents

Current	Standard number	Action
INS-LT-15R-01	same	Done: Rev 0.6 on engine
SOP-IT-UNIFI-01	same	Done: Rev 1.2 on engine; file renamed to its number
TN-NSH-B17-01, TN-CMT-P25-01	same	Done: Rev 0.3 on engine
BOM-OMT-HW-01	same	Done: Rev 0.2 on engine
MPM-TAP-2606-001 Rev A / B	TAP-GIL-M37-01	Done: Rev A → 1.0, Rev B → 1.1, rebuilt as 1.2; old number listed under Supersedes
MPM-TB-2604-001 (technical bulletin)	TBD	TB type not yet defined; assess when next needed
SORTA Monument Square survey Rev 0.1 (.docx)	SVY-SOR-MON-01	Done: rebuilt as PDF, Rev 0.2
Power Whip Cable drawing (engineering, MWT)	TBD	Engineering-owned part drawings keep their part-number scheme; DWG numbers are for drawings produced in this project

---

4. Revisions, files and folders

4.1 Revisions and status

• Revisions are numeric MAJOR.MINOR for every type, drawings included. Letter revisions (Rev A/B) belong to legacy and engineering part drawings only; when a lettered document is renumbered, issued letters map to 1.0, 1.1, … (Rev A → 1.0).
• 0.1, 0.2, … are drafts. Status shows as Draft (red in the info strip).
• 1.0 is the first release. Anything given to a customer as final must be ≥ 1.0. Drafts may be shared but stay marked Draft.
• After release: 1.1, 1.2 for corrections and clarifications, 2.0 when the substance (scope, values, procedure) changes.
• Once a revision has been shared outside your machine, any change to the PDF bumps the revision, formatting-only changes included. An unshared draft may be rebuilt in place.
• Revision history is mandatory. One line per revision: what changed, not "updates". The engine prints it as its own block at the end of the document (§6).
• A document that replaces a different document number lists it under Supersedes (TAP, SVY).

4.2 File names

{NUMBER}_{Customer}_{Short-Title}_Rev{X.Y}.pdf

• Underscores separate fields; hyphens join words within a field. No spaces.
• Example: TN-NSH-B17-01_Nashville_Bay17_Sign-Height-Change_Rev0.3.pdf
• The engine builds this name from slug="Nashville_Bay17_Sign-Height-Change".
• A Chinese edition adds _ZH before the revision: DWG-NSH-STAR-01_WeGo-Star_LED-Banner_Mounting-Options_ZH_Rev0.2.pdf (§12).

4.3 Folder layout

DOCUMENTATION PROJECT/
  _ASSETS/                        ← shared fonts and logos (mpm/): the only copies
  _STANDARDS/                     ← the standard, engine, templates, glossary, registry
  _INPUTS/                        ← reference material not tied to one project (outside drawings, examples)
  <CUSTOMER> <PROJECT>/           ← one folder per project, e.g. "NASHVILLE BAY 17"
    00_INDEX.md                   ← optional: status, contents, key numbers, owed items, sources
    <current PDFs>                ← latest revision of each document only
    _superseded/                  ← older revisions (moved here when a new rev is built)
    _INPUTS/                      ← what came in: site photos, screenshots, received drawings, quotes, field notes
    source/                       ← build.py, figs.py, img/ (prepared crops used in the PDF), _build/ (disposable)

• The root holds folders only. No PDFs, photos or loose files.
• _INPUTS/ holds originals and is never edited. Crops and annotated versions used in a document go in source/img/.
• Nothing is deleted from _superseded/. It is the issued history.
• "Claude outputs" is where the Claude app drops copies of files sent in chat. Treat it as transient. The project folder holds the record.

00_INDEX.md sections, as in Nashville Bay 17:

• Status in one paragraph
• What's in this folder
• Key numbers
• What's still owed
• Could not open
• Source threads

---

5. Units, numbers, dates

• Heights and clearances above grade: feet-inches, 12'-10", to the nearest 1/16 (units.ftin).
• Component and hardware dimensions: use the units of the source drawing or part. Metric parts stay metric (M8 × 1.25, 107 × 465 mm).
• Customer-facing documents: the first mention of a metric dimension gets the inch conversion: 312 mm (about 12-5/16 in.).
• Characters: use the true minus −, times ×, diameter Ø, degree ° and arrow →. Not -, x or ->.
• Numbers and units: in the mono font in tables and calcs. Put a space between value and unit (51.0 W, 0.53 A), except feet/inches and %.
• Precision: match the measurement; don't print 63.75 if you measured to ±0.1. One decimal for watts, two for amps.
• Dates: ISO in source (2026-11-05); displayed Nov 5, 2026 everywhere in the document.
• Unknowns: use TBC (red) in a cell, never a guess. List each TBC as an open item.

---

6. Page anatomy

Every MPM document, top to bottom. The engine generates the items marked ⚙.

1. ⚙ Running header (every page): MPM logo left; document type (uppercase) and NUMBER · REV X.Y right; gold rule.
2. ⚙ Kicker: Type · Customer · Subject in gold small caps.
3. Title (H1):
   • TN: name the thing being checked ("Bay 17 Sign: Mounting Height Change").
   • INS/SOP: name the outcome ("15" Reflective Sign: Shelter Post Mount").
4. Lede: 2–3 sentences; the situation and what the document does.
5. ⚙ Info strip: five cells: Document · Revision · Date (Effective for SOP) plus two type-specific cells (§9).
6. Opening:
   • TN: KPI tiles, then the dark Result box
   • INS/SOP: dark Before you start box
   • SVY: control table, dark About this document box, Status of this revision note
   • TAP: document-control table and the confidentiality notice (no dark box)
   • BOM: straight into the item tables
   • TSB: compliance pill, applicability table, dark Result box
   • PRO: parties, then KPI tiles (one key tile: the investment)
   • SOW: the opening paragraph naming the parties, the MSA, the end customer and the quotation
   • WO: status pill, parties (site · site contact · MPM dispatch), job table, Safety note
7. Body: sections with gold-ruled uppercase headings (doc.section). Figures and tables are numbered in order.
8. Close:
   • TN: Assumptions and open items
   • SVY: To verify list at the end of Part 2, then the appendices
   • INS: Final check
   • SOP: Setup checklist, Troubleshooting, Need help?
   • BOM: items to confirm note and sign-off lines
   • TAP: contacts, then the Prepared and approved by block
   • TSB: Compliance record, then Part 2 in the internal edition
   • PRO: Next steps, then a Submitted by block
   • SOW: milestones, assumptions and exclusions, optional Acceptance signatures
   • WO: Completion record and technician + site-contact signatures
9. ⚙ Revision history block: the last thing in every document, in its own cream block with a gold top rule. On the last page it sits at the bottom when it shares the page with content, or at the top when it lands on a page of its own.
10. ⚙ Running footer (every page): MESSAGE POINT MEDIA · Born to Innovate. Built to Last. left (tagline in Dark Gold, exactly as written); CUSTOMER · SUBJECT [· INTERNAL USE | CONFIDENTIAL] · NUMBER · Page x of y right. Override the context with footer= when it runs long; keep it under about 45 characters.

Page setup: US Letter portrait, margins 1.0 in. top, 0.7 in. bottom, 0.62 in. sides. DWG uses its own 11×17 landscape sheet (§9.7) instead of this anatomy.

Page breaks: start a new page (new_page=True) for a full-width figure page or a major part. Never leave a heading at the foot of a page. Headings are styled to stay with what follows, but check the PDF.

Classification:

• Public / Customer: no marking.
• Internal: footer says INTERNAL USE.
• Confidential: footer says CONFIDENTIAL, and page 1 carries a confidentiality notice naming the recipient and the governing NDA (TAP).

---

7. Visual system

7.1 Colour: each colour has one job

Token	Hex	Job
Ink	#232022	Text, dark boxes, primary linework
Gold	#DCBB4F	Brand accent: rules, step numbers, header underline
Dark Gold	#998643	Kickers, labels, FIG/TABLE tags, centrelines
Light Accent	#849698	Ledes, captions, secondary text, running footer
Cream	#F5F1EC	Info strip, notes, calc blocks
Line	#E6E0D8	Table rules, figure frames
Key	#FBF6E6	The one highlighted row or tile
Red	#A42D20	Warnings, failing values, limits, minimums, Draft status
Green	#3F6B3A	PASS, passing values
Blue / Grey	#2F5A8A / #B8B1A8	Data series only, never UI

Colours are the official MPM colour system (_ASSETS/README.md). Green PASS and the blue data series are functional additions, not brand colours, so keep them to status marks and data.

7.2 Type

• Montserrat: headings, kickers, labels, captions, table headers.
• Open Sans 9.6 pt: body. The brand's 11 pt applies to Word documents; dense technical PDFs stay at 9.6 pt (decided Nov 6, 2026).
• JetBrains Mono: numbers, dimensions, part numbers, calculations.
• All fonts come from _ASSETS/mpm/fonts/ and are embedded in every PDF. Never substitute Arial, Calibri or a system font.

7.2a Logo

• Running header: Logo-Gold-Black.png (gold icon, dark text) on white.
• Dark title blocks: Logo-Gold-White.png.
• Drawings: the SVG equivalent.
• The full selection guide is in _ASSETS/README.md.

7.3 Components: use these, don't invent new ones

Component	Engine call	Rules
Headline numbers	doc.kpis()	TN (and SVY summary): 3–4 tiles. Exactly one key tile (the answer); verdict tiles ok/bad.
Dark box	doc.result(), doc.before_you_start(), doc.dark()	Once per document, right after the info strip / KPIs. 2–6 bullets, key fact in bold.
Section	doc.section()	Short noun phrase. Uppercase is automatic.
Table	doc.table()	Header row is uppercase Montserrat with a gold underline, not the brand guide's dark header bar (decided Nov 6, 2026; reads better in dense numeric tables). Caption required if referenced. At most one KeyRow. Right-align numbers (r), mono for values (m, d).
Calculation	doc.calc()	Comment line, then name = symbolic = numeric = result. PASS/FAIL pill on the line that decides.
Figure	doc.figure()	Every drawn figure numbered and captioned; refer to it in text with [[fig:key]].
Screenshot / photo	doc.shot(), doc.shots()	Files in source/img/. Captioned, not numbered, because each belongs to its step. Crop to the relevant part and mark the control to tap with a gold box.
On-screen control	ui('Label')	Any button, tile or link the reader taps, named exactly as it appears on screen.
Process at a glance	doc.glance()	INS/SOP. 4–8 tiles, two-word label + detail. A step done by someone else is a greyed ✓ tile.
Step	doc.step()	INS/SOP. A side figure keeps the step whole. wide=True puts the figure below; the text stays whole and only the figure may move to the next page.
Special case	doc.special()	SOP/INS. A gold-framed panel for a situation only some readers hit (e.g. outside the U.S.). At most one or two per document.
BOM table	doc.bom()	Line numbers continue across sections; subtotal row per section; Pulled/Packed checkboxes.
Note	doc.note(kicker, body, tone)	See §7.4.
Checklist	doc.checklist(), doc.bullets(check=True)	Final check (INS, two columns), Setup checklist (SOP, one column), open items.
Assumptions / open items	doc.assumptions()	TN and SVY close with this. Open items start with a verb.
Sign-off	doc.signoff(), doc.approval()	Sign lines (BOM); Prepared and approved by block (TAP).
Control table	doc.kv()	Front matter of SVY and TAP: label / value rows (prepared for, supersedes, distribution …).
Part divider	doc.part()	SVY Part 1 / Part 2 / Appendices. internal=True marks an MPM-internal part.
Site photo	doc.photo(), doc.photos()	Numbered FIG, two side by side, max 2.7 in. tall. Every photo also appears in the photo log.
To-verify tag	verify()	Inline red tag on a point of record to confirm with the customer; each one also listed in the To verify note.
Field notes	doc.transcript()	Verbatim notebook transcription: spelling preserved, editorial text in [brackets].
Drawing sheet	Drawing(...), dwg.view(), dwg.sheet()	DWG only (§9.7).
Priced BOM	doc.priced()	PRO / SOW. SKU · description · qty · extended price, subtotal per group, grand total. Prices are numbers from the quotation; totals are computed (doc.price_total), never typed.
Milestones	doc.milestones(rows, expect=doc.price_total)	SOW (and PRO payment terms). The build fails if the milestones don't add up to the priced total.
Parties	doc.parties()	PRO / WO (SOW names them in the opening paragraph). MPM's block is brand.PROVIDER.
Status / compliance pill	doc.pill(text, colour)	TSB compliance: Mandatory red · Recommended gold · Informational grey. WO status: Dispatched gold · On site ink · Complete green · On hold red. One per document.
Fill-in record	doc.fields(), doc.table(..., cls="fill")	WO completion record; TSB compliance record (blank ruled rows).
Signatures	doc.signatures([(role, who)])	WO (technician + site contact); SOW Acceptance when the customer signs the SOW itself.

7.4 Note kickers (fixed vocabulary)

Tone	Kickers
info (cream/gold)	GOOD TO KNOW · CHECK · CHECK YOUR MARKS · TWO WAYS TO … · ON ANDROID · NEED HELP? · STATUS OF THIS REVISION · WHAT CHANGED IN THIS REVISION · topic-specific short label
warn (red)	WARNING · LINE VOLTAGE · CHECK POLARITY · WATCH FOR … · DON'T … · DRAFT · ITEMS TO CONFIRM BEFORE RELEASE · PROPRIETARY & CONFIDENTIAL
ok (green)	CONFIRMED · RESOLVED · CLOSED
verify (dashed)	TO VERIFY WITH {CUSTOMER} BEFORE RELEASE: points of record still to confirm (SVY)

Action required (TAP) uses doc.special(), not a note.

• Use a warn note only when getting it wrong can hurt someone or damage equipment.
• At most one warn note per step.

---

8. Writing

Voice:

• Plain, direct, specific.
• Short sentences.
• Active voice.
• No marketing language in technical documents.

Answer first:

• A TN's Result box must stand on its own.
• A reader who stops after the Result should have the right answer and its conditions.

Procedures (INS/SOP):

• Each step starts with a verb: Mark the hole locations. One step is one outcome.
• Numbered sub-steps: 3–6, one action each.
• Bold the object or value the reader must get right: plumb, 1/2 in. cobalt, breaker off.
• The step kicker names the tool, part or place for that step: Ø1/2 IN. COBALT BIT, UNIFI ENDPOINT.
• Every step that changes something physical gets a figure.
• Say what success looks like: a CHECK note, or a closing Final check list.

Numbers:

• Every number traces to a measurement, a document or a calculation shown in the document.
• Keep source numbers in one place (figs.py) and derive the rest in code. Never retype a derived value.

Names: use the customer's name for itself on first use in the kicker or lede (Nashville MCC (WeGo), SORTA / Metro); short form after that.

Unknowns:

• TBC in tables.
• Open items in TN/SVY.
• Draft · items to confirm warn note on BOM.
• Never paper over an unknown.

Attribution: when a requirement came from a person or email, the source is recorded in 00_INDEX.md, not in the customer document.

8.1 MPM brand voice in technical documents

Technical documents sit at the high formality · low energy · very high technical depth end of the MPM tone matrix (hardware/maintenance documentation). The MPM voice still applies:

• Expert partner, not vendor. Explain the why behind a step or a limit. Don't lecture and don't sell.
• Precise and purposeful. Exact names and numbers. No superlatives ("cutting-edge", "best-in-class", "revolutionary").
• Riders and passengers, not users, when the end audience is the public. Use transit agencies / agencies for customers in transit contexts.
• Accessibility is a design principle, not a checkbox. State ADA requirements as what makes the sign work for riders (reach range, audio), never as a compliance burden.
• Own the complexity. When something is hard, say so, then show the way through it. Proactive wording ("preventative check") rather than firefighting.
• Terminology:
  • native API integration (never wrapper or middleware)
  • MP.TV CMS in customer-facing documents
  • RDMC
  • GTFS-RT
  • publishing rules
  • hardware product names exactly as in the brand settings (e.g. MR Series, MR27)
• No conference-theme language (MPower motorsports metaphors) in documents.

Brand source: the mpm-brand-voice plugin (settings/brand-voice.local.md).

---

9. Per-type specifications

The two type-specific info-strip cells and the required section order for each type. Every type has an engine template in templates/<TYPE>/ with a preview PDF.

9.1 INS: Installation Guide (ready: templates/INS/)

• Info cells: Audience · Mount/Install type
• Sections:
  1. Before you start (dark box)
  2. Process at a glance (4–8 tiles)
  3. Hardware table + Tools table, side by side, kept together as one block
  4. Reference figure (template / drill schedule) if needed
  5. Walkthrough (numbered steps with figures)
  6. Final check (two-column checklist; last item "Photo of the finished install sent to MPM")

9.2 SOP: Standard Operating Procedure (ready: templates/SOP/)

• Info cells: Audience · Time needed
• Sections:
  1. Before you start
  2. Process at a glance (tiles labelled with who does it: IT / YOU)
  3. Walkthrough (numbered steps, screenshots as side figures)
  4. Special cases (e.g. Outside the U.S.), placed after the step they relate to
  5. Setup checklist (one column)
  6. Troubleshooting table (Problem · What to do)
  7. Need help? note
• Marked INTERNAL USE.

9.3 TN: Technical Note (ready: templates/TN/)

• Info cells: context (Site / Measured / Module) · criterion (Requirement / Deployment)
• Sections:
  1. KPI tiles (3–4)
  2. Result
  3. Evidence: comparison table → calculation → figures
  4. Assumptions and open items
• 1–3 pages. If it needs more, it is probably two notes or a report.

9.4 BOM: Bill of Materials (ready: templates/BOM/)

• Info cells: Customer · Prepared by
• Columns: # · Item · Specification · Qty · UOM · Part no. · Pulled · Packed
• Grouping: by category (Fasteners, Sealing & consumables, …), each with a subtotal row.
• Close: Draft · items to confirm before release warn note while < 1.0, then sign-off (Pulled by · Checked by · Date).

9.5 SVY: Site Survey (ready: templates/SVY/)

• Info cells: Survey date · Surveyor
• Front matter:
  • Prepared for / by
  • Basis (notes, photos, drawings received)
  • About this document
• Part 1, Summary of Findings (customer):
  • Purpose
  • Scope
  • What we found (table by stop or family)
  • What it means
• Part 2, Engineering Detail (MPM-internal):
  • Survey record
  • Inventory
  • One section per mount family (observations → design constraints)
  • Power & data
  • TO VERIFY list
• Appendices: A, photo log (# · time · cluster · file ID · subject, citing the figure numbers); B, verbatim field-notes transcription with the notebook pages.
• Release to the customer: the PDF is marked INTERNAL USE while it carries Part 2. Release Part 1 + appendices as a customer edition (to be added to the engine when the first survey is released).

9.6 TAP: Technical Action Plan (ready: templates/TAP/)

• Info cells: Customer · Engagement dates
• Front matter:
  • Document-control table: Supersedes / References · Distribution · Affected products · Personnel · Site
  • Confidentiality notice
• Sections (numbered in the heading text):
  1. Purpose and scope (with What changed in this revision from 1.1 on)
  2. Background: known-issue register and failure groups
  3. Information required from the customer (Action required panel)
  4. Personnel: field technician, coordination, oversight
  5. Parts and equipment kit
  6. Timeline and daily schedule
  7. Procedures by failure group, then disposition
  8. Open items and decisions
  9. Acceptance criteria (per unit, engagement)
  10. Daily reporting
  11. Escalation and contacts
• Close: Prepared and approved by block.

9.7 DWG: Drawing sheet (ready: templates/DWG/)

• Sheet: 11×17 landscape, zone grid (8–1 across, D–A down), header bar with logo, discipline and DWG NO · SHEET · REV.
• View area: a 6 × 4 grid. Each view has a numbered bubble, a title and a scale.
• Right column, top to bottom:
  • Schedule: tag · designation · description · qty, with tags as gold bubbles that match the callouts on the views
  • General notes, numbered
  • Title block: project, title, client, location, scale, drawn / checked / approved, dwg no., sheet n of N, rev, date
  • Revision history
  • Confidentiality strip with the tagline
• Drafting conventions:
  • Ink linework; centrelines Dark Gold, long-dash-dot; hidden lines dashed
  • Dimensions in mm (JetBrains Mono) with extension lines
  • "Do not scale from drawing" in the general notes
• Revisions: numeric like every other type (§4.1). Multi-sheet sets share one number and revision.

9.8 TSB: Technical Service Bulletin (ready: templates/TSB/)

• Info cells: Compliance · Effective
• Two editions from one build.py:
  • Customer edition: classification customer; slug ends _TSB.
  • Internal edition: classification internal; slug ends _TSB-Internal; adds Part 2 Diagnostic detail (root cause, field data, support notes).
  • Same number, same revision, issued together. The customer edition never contains Part 2.
• Front: compliance pill; applicability table (Applies to · Affected units · Not affected · Labor estimate · Supersedes · Distribution); dark Result box (what happens, what to do, by when).
• Sections: 1 Symptom · 2 Cause · 3 Corrective action (steps; reference an INS for anything long) · 4 Verification · 5 Parts.
• Close: Compliance record, a blank table (unit serial, site, date, technician, done) the field fills in.
• Compliance levels: Mandatory (failure or safety; fix by a stated date) · Recommended (fix at the next visit) · Informational (no action).

9.9 PRO: Proposal (ready: templates/PRO/)

• Info cells: Prepared for · Valid until
• Front: parties (Prepared for · Prepared by = brand.PROVIDER); KPI tiles with the investment as the one key tile.
• Sections (numbered in the heading text): 1 Your situation · 2 Proposed solution · 3 Why Message Point Media · 4 Scope summary (phase · MPM provides · agency provides) · 5 Investment (doc.priced, with a Pricing note naming the quotation and validity) · 6 Timeline · 7 Assumptions and exclusions · 8 Next steps.
• Close: Submitted by block (doc.approval(..., label="Submitted by")).
• Rules: every price comes from a quotation; §3 holds facts you can back up (deployments, agencies, years, uptime), never superlatives. Marked CONFIDENTIAL. After award, write the SOW; don't revise the PRO into one.

9.10 SOW: Statement of Work (ready: templates/SOW/)

• Info cells: Customer · Quotation
• Opening paragraph: made by and between Customer and Message Point Media of Alabama, Inc (MPM); subject to the Master Services Agreement; for the benefit of the End Customer; pricing per Quotation S#####, its date and expiry.
• Sections (numbered 1.0, 2.1, 2.1.1 in the heading text):
  1. 1.0 Scope overview (say what is not included when a reader might assume it is)
  2. 2.0 Project deliverables: 2.1 Hardware (list, then 2.1.1 priced BOM per the quotation) · 2.2 Documentation (document · purpose)
  3. 3.0 Scope of work: 3.1 Initiation and scheduling · 3.2 Site confirmation · 3.3 Procurement and provisioning · 3.4 Delivery · 3.5 Installation · 3.6 Operational verification · 3.7 Warranty (name the warranty policy)
  4. 4.0 Project milestones (doc.milestones(..., expect=doc.price_total))
  5. 5.0 Assumptions and exclusions
  6. 6.0 Acceptance: signatures, only when the customer signs the SOW itself
• Revisions: 0.x while negotiating; 1.0 = executed. Reference: SOW_Nashville_Replacement_Sign_S01012 (Aug 2026), in NASHVILLE BAY 17/_INPUTS/04_Commercial/.

9.11 WO: Field Work Order (ready: templates/WO/)

• Info cells: Scheduled · Assigned to
• Front: status pill; parties (Site with coordinates · Site contact · MPM dispatch); job table (Customer / project · Installer · Access · Reference documents); Safety note.
• Sections: Work to be performed (checkboxes, each an action) · Parts and materials (doc.bom, Staged / Used checks) · Return with this work order (photos, serials, measured deviations).
• Close: Completion record (doc.fields: arrival, departure, serials installed and removed, online on MP.TV, issues) and technician + site-contact signatures.
• Rules: marked INTERNAL USE (contacts, access). Issued at 1.0; a re-dispatch with a changed scope or date is 1.1. The signed paper copy is scanned into the project's _INPUTS/ and never edited; the PDF stays as issued. The how-to lives in the referenced INS, not in the WO.

---

10. Before you issue (checklist)

• Number registered in registry.md; file name matches §4.2
• Revision bumped; history line says what changed
• Result / Before-you-start box stands on its own
• Every figure and table numbered, captioned and referred to in the text
• Every number traceable; no retyped derived values; TBCs listed as open items
• Units and characters per §5 (− × Ø °)
• Classification correct; confidential documents carry the NDA notice
• PRO / SOW: prices match the quotation line for line; milestones add up (the build checks); validity date set
• TSB: customer edition opened and checked to contain no Part 2
• Opened the PDF and looked at every page: no orphan headings, no clipped figures, no stray near-empty last page
• Previous revision moved to _superseded/
• Chinese edition (if any) rebuilt at the same revision, its previous revision also moved to _superseded/

---

11. Asking Claude for a document

Say the type and the subject; Claude reads this standard and the template:

"TN for CommTran: per-sign power roll-up for the 4×2 Pingo layout" "Rev the Nashville TN — hanging hardware is 2 in. taller than the old" "INS for LakeTran: 15-inch sign on a round pole"

Claude asks for the number you claimed in the shared registry, builds in <PROJECT>/source/ with mpmdoc, and puts the PDF in the project folder. Anything it can't source becomes a TBC or an open item, never a guess.

How builds run:

• Claude needs your kit folder: open it in the Claude desktop app (or link the computer that holds it), and install the mpm-technical-documents plugin from _PLUGIN/.
• Builds need Python 3.10+ with Playwright/Chromium and poppler. Run setup.sh once (see START_HERE.md); then python3 build.py in a project's source/ folder builds the PDF. When Claude can't run Python on your computer, it builds in its cloud workspace and writes the PDF back to your folder.

Numbers are claimed in the shared registry. The registry.md in your kit is a snapshot. The master registry is kept in one shared place set by MPM Technical Services: claim a number there before your first build, then copy the row into your own registry.md. A number is never reused, even for an abandoned draft.

Keeping documents. Issued PDFs go to the shared project location for the job, together with their source/ folder, so the next revision starts from the same source.

The mpm-technical-documents plugin carries this workflow, so any Claude session follows it.

---

12. Chinese editions (简体中文) for manufacturers

For drawings and technical notes going to a Chinese manufacturer, MPM issues a Chinese edition alongside the English one.

Scope. TN and DWG only (mpmdoc.i18n.TYPES). Other types are assessed when needed.

What it is.

• A second PDF of the same document: same number, slug, revision, figures and geometry.
  • Body text is in Simplified Chinese.
  • Frame labels are bilingual (图号 Dwg no., 部件表 · Schedule), so MPM staff can find their way around it.
• File name: {NUMBER}_{slug}_ZH_Rev{X.Y}.pdf, kept in the project folder next to the English edition.
• The English edition governs. Every Chinese edition says so:
  • TN: a line under the masthead.
  • DWG: a general note on every sheet.
  • The engine adds the statement automatically unless a note already carries it.
• Revisions move together: a new English revision means a new Chinese edition at the same revision. The history lines are translated; the revision numbers and dates are identical.

How it's built.

• source/build_zh.py sits next to the English build.py; start from templates/TN/build_zh.py or templates/DWG/build_zh.py. It shares figs.py with the English build and passes lang="zh" to Doc / Drawing.
• Build the English edition first. The engine refuses to build a Chinese edition unless the English PDF at the same revision is already in the project folder.
• Write the Chinese strings in the same order as build.py, so the two files can be compared side by side.
• Figure text: goes through i18n.Translator.
  • Lookup order: the document's own TERMS table, then the master glossary _STANDARDS/glossary_zh.md.
  • tr.check() fails the build on any English left in a figure.
  • Numbers with units, tags (S-1, M3), part numbers and standards pass through unchanged.
• Terms: one English term, one Chinese term.
  • A term that will recur goes in glossary_zh.md; a sentence specific to one document goes in its TERMS.
  • When a manufacturer corrects a term, change the glossary and rebuild the Chinese editions that use it.
• Units: mm first, imperial in [ ]; mass in kg, with lb in [ ] where the source is lb. If figs.py formats dimensions through a function F, build_zh.py replaces it before drawing the figures.
• Keep in Latin script: part and model numbers, tags, units, standards (ADA 307, IP66, UL 48), place and station names, brand names, the tagline.
• Dates: shown as 2026年11月9日.

Font.

• Chinese text is set in MPM SC: Noto Sans CJK SC (SIL OFL), cut to GB2312 and converted to TrueType in _ASSETS/mpm/fonts/cjk/ by make_cjk.py.
• The engine embeds only the characters each document uses, and adds MPM SC as the fallback to every font stack. Latin text and numbers stay in Montserrat / Open Sans / JetBrains Mono.
• No system font is used, so a build looks the same on any machine.

---

Standard revision history

Version	Date	Change
1.3	Nov 9, 2026	Chinese editions for TN and DWG (§12): lang="zh" in the engine, MPM SC font, master glossary glossary_zh.md, build_zh.py templates; _ZH file names (§4.2); checklist line (§10).
1.2	Nov 6, 2026	Added TSB, PRO, SOW and WO (§1, §3.1, §6, §7.3, §9.8–9.11, §10) with templates; new components priced, milestones, fields; MPM styling for parties, pills and signatures.
1.1	Nov 6, 2026	Brand references updated.
1.0	Nov 6, 2026	Released. MPM document types TN, INS, SOP, BOM, SVY, TAP and DWG with engine templates; shared _ASSETS; folder layout with _superseded/ and _INPUTS/.