# audit.json schema

The report builder (`scripts/build_report.py`) turns one JSON file into a clean, white-label `.docx`. Your job in Step 6 is to write this JSON from your analysis, then run the script. The script owns all the styling, so you never touch fonts or colors. Write every string in the voice defined in `references/report-style.md`. Reproduce quotes from the client's assets verbatim, even inside these strings.

The `prepared_by`, `logo_path`, and `accent` fields come from the practitioner's saved author profile (see the "Set up the author profile" step in SKILL.md). Copy them in from the profile; don't ask again each run.

## How to run it

```
python scripts/build_report.py audit.json <output_dir>
```

It writes `<brand>-messaging-audit.docx`. No logo ships with the Skill; a logo appears only if the profile's `logo_path` points to the practitioner's own image. The script needs `python-docx` (`pip install python-docx`). To also produce a PDF, add `--pdf` at the end; that needs LibreOffice, and if it isn't installed the `.docx` still builds and the marketer can Save As PDF.

## Fields

| Field | Type | What it is |
|---|---|---|
| `brand` | string | The brand being audited. Used in the title and file name. |
| `prepared_by` | string | From the profile. Who prepared it (the marketer or their practice). Shows in the "Prepared by" line and footer. |
| `logo_path` | string, optional | From the profile. Absolute path to the practitioner's own logo image. Omit for a clean, name-only cover. No logo ships with the Skill. |
| `accent` | string, optional | From the profile. Primary hex color (for example `#23514C`) for the color-block cover, matrix header, section labels, priority numbers, gap labels, and Your Strategic Take outline. Use a dark color so white text reads on it. Omit for the deep-teal default. |
| `accent2` | string, optional | From the profile. Secondary hex color (for example `#9B84C4`) for the section rules, cover accent line, matrix zebra rows, and next-step box tint. A mid-tone reads best. Omit for the lilac default. Rating colors are fixed and not affected by either accent. |
| `date` | string | Human-readable date, for example "July 12, 2026". |
| `asset_count` | number | How many assets were audited. |
| `subtitle` | string, optional | One-line descriptor under the title on the cover. If omitted, the builder writes "An inventory and consistency read of [brand]'s existing messaging across [n] assets." |
| `exec_summary` | string | Section 1. Three to five sentences. Overall read, the single most important fix, what is and isn't covered. |
| `overall_read` | string | One plain-language sentence summarizing the consistency pattern. Shown above the scorecard. |
| `scorecard` | array | One entry per core element: `{"element": "...", "rating": "aligned|drifting|contradictory|absent"}`. Drives the color-coded scorecard. |
| `assets_audited` | string | Section 2. Each asset with its intended audience. |
| `out_of_scope` | string | Section 2. What's out of scope or unreachable. |
| `matrix` | object | Section 3. `{"assets": ["Asset 1", ...], "rows": [{"element": "...", "values": ["quote or ''", ...]}]}`. An empty string renders as "(absent)". Keep `values` in the same order as `assets`. |
| `findings` | array | Section 4. Each: `{"element": "...", "rating": "...", "evidence": ["quote", "quote"], "so_what": "..."}`. Lead with the worst-scoring elements. |
| `gaps` | array | Section 5. Each: `{"type": "Missing element|Undifferentiated claim|Unsupported claim|Internal jargon|Audience mismatch|Outdated / orphaned messaging|Overclaim / credibility risk|Buried lede", "text": "..."}`. |
| `fixes` | array | Section 6. Ordered, most important first. Each: `{"title": "...", "why": "...", "rating": "...", "effort": "Low|Medium|High|...", "next": "..."}`. The script numbers them. |
| `strategic_take` | array | Section 7. Each: `{"q": "the question", "note": "why it's a human call"}`. |
| `next_step` | string | Section 8. One or two sentences pointing to defining the corrected messaging. |

## Rating values
Use exactly these lowercase strings in `rating` fields so the colors map correctly: `aligned` (teal), `drifting` (amber), `contradictory` (pink), `absent` (grey). In `fixes`, the `rating` can also be a plain label like "Unsupported" since it's shown as text, not a color.

## Minimal example
See `references/example-audit.md` for a full worked audit in prose. The same content maps field-for-field into this JSON. Keep it honest: if an element is absent, leave the matrix cell empty and mark the scorecard `absent`. Never invent content to fill a field.


## `show_platform_credit` (optional, boolean, default true)
Whether the report renders the footer methodology-credit line ("This messaging audit is based on Kara Parlin's framework and process" plus the Firebrand Intelligence Engine link). Omit it or set true to show the credit; set false to suppress it for a fully unattributed white-label report.
