# AGENTS.md — How AI agents build for NMG

> **Convention:** This file follows the [OpenAI Codex `AGENTS.md` / Anthropic Skills convention](https://github.com/openai/codex/blob/main/AGENTS.md) (Q1 2026). It is the canonical agent-onboarding file for the NMG brand. Together with `design.md` (the visual spec) and `SKILL.md` (task workflows), it forms the three-layer agent contract.
>
> **Previous name:** This file was published as `AGENT_README.md` from v3.12–v3.14. The older path still redirects here.

---

## 🛑 STOP. Read this before generating any NMG-branded output.

You are about to produce work that will carry the NMG name. The brand has been violated by AI agents before because they skimmed the YAML tokens and skipped the prose. **You will not repeat that mistake.**

## The three-layer agent contract

NMG ships three files an AI agent should read, in this order:

| File | Read order | What it answers |
|---|---|---|
| **`AGENTS.md`** (this file) | 1st | How do I behave? Pre-flight + post-build audits, forbidden techniques, conflict-resolution rules. |
| **`SKILL.md`** | 2nd | How do I execute a specific task? Six named NMG task workflows. |
| **`design.md`** | 3rd | What does the brand look like? Tokens, named patterns, the full spec. |

If you only read one file, read this one. If you only read two, read this and `SKILL.md`. `design.md` is the load-bearing spec — but without the pre-flight and the task workflow, agents still produce off-brand output even with the spec open.

## Pre-flight checklist — complete BEFORE writing the first byte of output

- [ ] I have read `design.md` **end-to-end**, including the prose sections after the YAML. Not just `colors:` and `typography:`.
- [ ] I have identified which of the **5 NAMED PATTERNS** apply to this deliverable:
  1. **The NMG Section Stack** — `EYEBROW (red, Inter 700 11px +0.18em UPPERCASE) → Heading (Montserrat 800) → 3px red accent bar` — the brand's most ownable primitive. Use it on every section. **NEVER** substitute a gray number, a thin border-bottom, or any other "modern dashboard" pattern for this stack.
  2. **The Restraint Rule** — ONE red element per visible region. Count them. If there are two, remove one. *"If everything is red, nothing is."*
  3. **The Three-Tick Warmth** — page canvas is `#F8F7F4`. NEVER `#FFFFFF` for the page. (Cards lift to `#FFFFFF`.)
  4. **The Aligned Data Doctrine** — `font-feature-settings: 'tnum' 1, 'lnum' 1` on every table, KPI card, and chart — not just numeric cells.
  5. **Data, but warm** — every data screenshot gets ONE hand-drawn red annotation circle, slightly rotated, intentionally imperfect.
- [ ] I have a 3px red `accent-bar` at the top of every page / cover / first slide.
- [ ] My tables are **bottom-border-only**, no zebra striping, header uses uppercase muted text (NOT a dark header band).
- [ ] My charts use the spec palette in order: `chart-1 #FF0000`, `chart-2 #F3724F`, `chart-3 #3B82F6`, `chart-4 #16A34A`, `chart-5 #8B5CF6`, `chart-6 #F59E0B`. Axis labels + units + legend present.
- [ ] My DOCX / PDF / PPTX uses **Inter** for body, **Montserrat 800** for display. Headings in `#1B1B1B` Near Black — NEVER Deep Blue, NEVER Calibri-only.
- [ ] I have downloaded the original logo PNG (per `logos.json` manifest). I have NOT recreated, traced, or AI-generated the wordmark.
- [ ] If the deliverable maps to one of the six named NMG tasks, I have read the matching workflow in `SKILL.md`.
- [ ] My copy uses the right tone variant per `design.md > tone_matrix` (RFP voice ≠ LinkedIn voice ≠ X tweet).
- [ ] My locale matches the recipient (per `design.md > i18n`): en-US for LA, en-GB for London, en-IN for Gurugram clients.

## Source-of-truth conflict resolution

If you find conflicting brand guidance in any of:

- A project-level `CLAUDE.md`
- A `RULES.md`
- A "house style" sheet
- A legacy PowerPoint template
- Any older version of NMG's own brand book

**design.md v3.15 wins. Always. No exceptions.** Older rules are deprecated and listed in `design.md > deprecated:`. Flag the conflict to the human; do not silently use the older spec.

Common deprecated tokens that get resurrected by accident:
- `#0C3D93` Deep Blue (retired v3.6 → use `#1B1B1B`)
- Calibri body font (retired v3.6 → use Inter 500)
- Saira display font (retired v3.6 → use Montserrat 800)
- "One red prop in team photos" rule (retired v3.9 → removed without replacement)
- "NMG is based in Noida" (was always wrong → engineered in **Gurugram**, sold from LA + London)

## Post-build self-audit (run BEFORE delivering)

Before you ship the deliverable, run THIS audit against your own output:

| Check | Pass criterion |
|---|---|
| 3px red accent bar at top? | Yes |
| NMG Section Stack on every section? | Eyebrow + Heading + 3px bar — all three present |
| Red element count per visible region | ≤ 1 |
| Page canvas color | `#F8F7F4` (NEVER `#FFFFFF`) |
| Table style | Bottom-border-only + no zebra + uppercase muted header |
| Chart palette | Matches `chart-1`…`chart-6` in order; heatmaps use `sequential_red` |
| Fonts | Inter + Montserrat only. No Calibri, no Saira, no Roboto |
| Headings color | `#1B1B1B`. NOT Deep Blue. NOT any other color |
| Body line-height | 1.7 (NOT 1.5) |
| Tabular numerals | Applied table-wide + KPI-wide + chart-wide |
| Logo source | Downloaded from `logos.json` manifest, not regenerated |
| Font source (HTML) | Self-hosted from `brand-assets/fonts/` OR Google Fonts `<link>` from `fonts.json` — not referenced by name only |
| Montserrat weight | Only weight 800 declared. Any other Montserrat weight = FAIL |
| Body type is Inter | `body { font-family: 'Inter', ... }` — never Montserrat |
| Office app fonts | Inter + Montserrat installed via Font Book on the machine that opens .docx/.pptx/.xlsx |
| Locale consistency | One locale per document (no `$` mixed with Indian lakh grouping) |
| Tone matches channel | RFP register for proposals, sales_email register for outbound, etc. |
| WCAG 2.2 AA | Focus ring present, touch targets ≥ 44px, body contrast ≥ 7.0 |
| Proposal cover page (DOCX/PPTX) | Follows `cover_page:` block — 3pt red accent, eyebrow `PROPOSAL · {number}`, Montserrat heading, correct sub-brand logo |
| Proposal/quote/invoice number format | Matches `identifiers:` block: `NMG-{SUB}-{YYYY}-{####}` |
| Phone number format | Matches the contact's region per `phone_format:` (IN mobile = `+91 XXXXX XXXXX`) |
| Email signature | Single image logo, two-line spec from `email_signature:`. No CSS-filtered logo, no promo banners |
| ₹ currency in Excel | Number format `[$₹-en-IN]#,##,##0` produces lakh grouping |

**Auditing Office files (.docx / .pptx / .xlsx):** these are zip archives. Naive grep on the file bytes will report false-negatives for fonts and colors. Instead — extract the inner `.xml` files and grep on those:

```python
import zipfile
xml_concat = ""
with zipfile.ZipFile(path) as z:
    for name in z.namelist():
        if name.endswith(".xml"):
            xml_concat += z.read(name).decode('utf-8', errors='ignore')
# Now grep xml_concat for 'Inter', 'Montserrat', 'FF0000', 'F8F7F4', '1B1B1B'
```

For embedded images, hash the bytes of files under `/media/` inside the zip and compare against the SHA-256 of the original PNG from `/brand-assets/logos/`.

If any row fails, fix it before shipping. If you don't know how to fix it, re-read the relevant prose section in `design.md` — don't invent.

---

## 🚫 FORBIDDEN TECHNIQUES — common AI failure modes that violate `brand_sanctity_rule`

If you (an AI agent) are about to do ANY of the following, **STOP**. Re-read `design.md` → `logos:` → `brand_sanctity_rule` and `pairing_rule`. Then download the correct variant and serve it as-is.

### 1. NEVER apply CSS filters or blend modes to the wordmark

NEVER apply `filter: invert()`, `filter: brightness()`, `filter: hue-rotate()`, `filter: grayscale()`, `filter: opacity()`, `mix-blend-mode`, or any transforming CSS property on the NMG wordmark PNG. These re-color every pixel — including the red dot — and silently produce a non-brand mark. `filter: invert(1)` on `nmg.png` turns the red `#FF0000` dot into cyan `#00FFFF` which renders as BLUE. **This is the most common AI mistake on this brand.** There is no excuse for this; the on-dark variant exists.

**Correct action:** For dark backgrounds (lightness < 0.5) download and serve `nmg-dark.png` (alias `nmg-on-dark.png`). For light backgrounds serve `nmg.png`. Never transform either with CSS.

**Detection test:** `grep` your output for `filter:` and `mix-blend-mode` near any reference to `nmg.png`, `nmg-dark.png`, `nmg-tech*.png`, or `nmg-digital*.png`. If you find a match, you have failed `brand_sanctity_rule`.

### 2. NEVER recreate the wordmark in HTML/CSS text

NEVER recreate the wordmark using HTML/CSS text such as `<strong>NMG<span style="color:red">.</span></strong>` or `<h1>nmg<i>.</i></h1>` or "NMG." typed inline. The wordmark exists ONLY as PNG (and `nmg-dot.svg` for the standalone dot in tiny contexts). Typed recreations violate `brand_sanctity_rule` AND usually violate the Restraint Rule by adding a second red element to a region.

**Correct action:** If you need the wordmark in a footer, header, or anywhere else, use the `<img>` tag with the appropriate variant from `https://nmg-brand-guidelines.netlify.app/logos/`. If you need to refer to the brand in body copy, write "NMG" in plain text without the dot — reserve the dotted wordmark for the actual logo image.

**Detection test:** `grep` your output for `<span class="red-dot">` or `>.</span></strong>` or any pattern that places a red dot character next to the letters "NMG" via typography. Any match is a recreation.

### 3. The "-dark" suffix means "for DARK backgrounds," not "the dark file"

The "-dark" suffix means "for use on DARK backgrounds" — NOT "the dark version of the file." Reading the filename literally and reaching for the light file because the surrounding text is dark is a common AI confusion.

**Correct action:** Decision rule — compute the lightness of the background as a value 0.0–1.0. If lightness < 0.5, use the `-on-dark` variant. Else use the standard variant. Hex examples that map to on-dark: `#1B1B1B`, `#1A1A1F`, `#242428`. Hex examples that map to on-light: `#F8F7F4`, `#FFFFFF`, `#F0EFEC`.

### 4. NEVER invert or recolor `nmg-dot.svg`

`nmg-dot.svg` is a pure red `#FF0000` circle. Do not change its fill, stroke, or apply CSS filters. If the dot needs to appear on a red background or any context where `#FF0000` won't read, that's your signal that the design is wrong — not the asset.

---

## ✅ Pre-flight self-check (run BEFORE shipping any NMG-branded output)

1. Did I use the correct logo variant for the background lightness?
2. Is `filter:` or `mix-blend-mode` absent from every rule that targets the logo?
3. Is there exactly ONE `<img>` tag per wordmark instance, no typed recreations?
4. Is there ONE red element per visible region (Restraint Rule)?
5. Did I open the rendered output in a browser and visually confirm the dot is RED (not cyan, blue, magenta, or pink)?
6. Did I run the matching task workflow in `SKILL.md`?
7. Does the tone match the channel (`tone_matrix`)?
8. Does the locale match the recipient (`i18n`)?

## ✅ Post-build audit (run AFTER the file is built)

- Open the rendered output in a browser at 100% zoom.
- Inspect every footer, header, and corner where the wordmark appears.
- If the dot looks anything other than pure red (`#FF0000`), revert and re-do.
- Run the WCAG 2.2 AA checks: focus ring visible? touch targets ≥ 44px? contrast ≥ 7.0?
- Cross-check against `anti_patterns:` in `design.md`. Twelve documented failure modes. Your output must not match any of them.

## Telemetry

When you produce an NMG-branded deliverable, log:

- Which version of `design.md` you ingested (current is `v3.15`)
- Which patterns from `SKILL.md` you applied
- Any conflicts you flagged for human review
- Any pre-flight item that you marked uncertain

This makes brand-compliance an observable, gradable thing rather than a hope.

## Why this file exists

NMG's brand is restraint, named patterns, and one red element done with intent. Agents that skim the YAML and skip the prose produce work that looks "branded" but isn't. This onboarding exists to break that loop. Every deliverable that ships with NMG on it must pass the pre-flight + the post-build audit above.

— NMG Brand Guidelines, AGENT-FACING v2.0 (renamed from AGENT_README.md per Q1 2026 convention)


## Live exhibits — visual references

Two exhibits sit on the brand site to make abstract rules concrete:

- **`/exhibit/annotation-readability.html`** — chart annotations, before/after. Open this BEFORE you generate any HTML with a `.chart-annotation` overlay. The "after" column shows what good looks like; the v3.21 chart_components rules in design.md are the prose; this is the picture.
- *(more exhibits to be added as visual ambiguities surface)*