# Shared report HTML contract

Canonical rendering contract for polished local CSE report artifacts: the war room agenda,
team shoutouts, and any other briefing an operator opens in a browser or prints for a meeting.
The stylesheet lives beside this file at [`report-html/cse-report.css`](report-html/cse-report.css).

This contract governs presentation only. Evidence rules stay with the calling skill; a pretty
report built on unsourced claims is still a failed report.

## When to render HTML

Render the HTML artifact when the report is meant to be read by a group: a meeting agenda, a
shoutouts segment, an onsite briefing, a readout an operator will screen-share or print.
Skip it for working notes, scratch analysis, and anything headed straight into another tool.

Always write the markdown source first, then render HTML beside it with the same basename.
The markdown stays the editable source of truth; the HTML is the presentation copy.

## Document shape

One self-contained `.html` file. No build step, no external CSS, no JavaScript framework.
The only permitted remote references are the Postman logo, Google Fonts, and the Postman
Degular `@font-face` sources already present in the stylesheet.

Assemble in this order:

1. `<!DOCTYPE html>` and `<html lang="en">`.
2. `<head>`: UTF-8 charset, viewport, a one-sentence `meta name="description"`, a title in
   `Subject - Qualifier` form, the Postman favicon, font preconnects and the fonts stylesheet
   link, then the entire canonical stylesheet inlined in a single `<style>` element.
3. `<header class="operator-bar">`: brand link back to `#top`, a `nav.jump` with one anchor per
   major section, and a `button.bar-btn#print`.
4. `<main id="top">` holding `section.hero`, `section.north-star`, the body sections, and an
   optional `section.closer`.
5. `<footer class="footer">`.
6. A single small inline `<script>` wiring the print button and nothing else.

### Hero

`.eyebrow` names the occasion, `h1` names the artifact, `.lede` is one sentence stating what the
reader is about to get, and `.hero-date` carries the window or meeting date.

### North star

One `h2.ns-head` sentence that says what actually happened, in plain language, without framing.
Then `.ns-strip` with three or four numbers that need no explanation. Each strip cell is a
`.ns-step` label, a `<b>` figure, and a `.ns-desc` clause. Only use figures traceable to a cited
artifact. If the week produced no clean numbers, cut the strip rather than inventing one.

### Body sections

Each entry is an `article.block` with a stable `id` and `tabindex="-1"` so the jump nav lands on
it. Inside: a `.person-name` or section heading, a `.headline` clause, prose, and where the
evidence supports it a `.quote` with `cite`, a `.block-grid` of `.cue` cards, and an `.evidence`
list of artifact identifiers. Keep artifact identifiers in `.block-code` monospace.

Evidence identifiers are the Jira key, `repo#PR`, `repo@sha`, Slack channel plus timestamp, or
communication id. They are the receipt, so they render as text, not as decoration.

## Copy rules

The prose constitution applies to every word in the HTML exactly as it applies to markdown.
See [`../../../docs/flows/voice-guard/prose-constitution.md`](../../../docs/flows/voice-guard/prose-constitution.md).

ASCII only in the rendered body. These characters must not appear:

| Banned | Use instead |
|---|---|
| em dash, en dash | a period, a comma, or a restructured sentence |
| curly quotes, curly apostrophes | `"` and `'` |
| bullet, arrow glyphs | list markup, or plain words |
| emoji | nothing |

Write around the punctuation rather than substituting a lookalike. A sentence that needs an em
dash usually wants to be two sentences.

## Print and responsive

The stylesheet already carries the print and responsive rules. Do not weaken them:

- `@media print` hides the operator bar and footer, flattens the north star to ink on white,
  and sets `break-inside: avoid` on cards so a person or agenda item never splits across pages.
- Breakpoints at 980px and 680px collapse the grids to a single column.
- `@media (prefers-reduced-motion: reduce)` disables smooth scrolling and transitions.

If a report needs a new component, add it to the stylesheet with matching print and responsive
rules in the same edit.

## Validation

Run before handing the file to the operator. Every check must pass.

```sh
report="$HOME/.cse-tools/reports/<basename>.html"

# 1. No non-ASCII anywhere in the file.
LC_ALL=C grep -n '[^ -~\t]' "$report" && echo 'FAIL: non-ASCII' || echo 'ok: ascii'

# 2. Structure present.
for tag in '<!DOCTYPE html>' 'operator-bar' 'north-star' '</html>'; do
  grep -qF "$tag" "$report" || echo "FAIL: missing $tag"
done

# 3. Every article opens and closes.
test "$(grep -c '<article' "$report")" = "$(grep -c '</article>' "$report")" \
  || echo 'FAIL: unbalanced article tags'

# 4. Every jump anchor resolves to a real id.
for a in $(grep -oE 'href="#[a-z0-9-]+"' "$report" | cut -d'#' -f2 | tr -d '"'); do
  grep -qE "id=\"$a\"" "$report" || echo "FAIL: dead jump anchor #$a"
done
```

Also confirm by reading: every figure in `.ns-strip` and every claim in a `.headline` traces to
an identifier that appears in that entry's `.evidence` list.

## Output location

Write both files to `~/.cse-tools/reports/` using `YYYY-MM-DD-<slug>.md` and
`YYYY-MM-DD-<slug>.html`. Report the absolute path of both to the operator.

When a skill defines its own output directory, that directory wins and this naming convention
still applies inside it.
