Branded report template (agents deliver ready-made report pages)

What it is

When an Omniscio agent produces a report deliverable — research findings, a tool roundup, recommendations, an audit, a comparison — it no longer designs an HTML page from scratch. The product ships ONE standard Aurora-branded report template, renders it server-side from plain data, and every locally-spawned session is automatically told to use it.

Where to find it

What the user sees

Reports published to Shares arrive on-brand and consistent: the Omniscio orb + the all-caps OMNISCIO logotype, restrained aurora color, and a readable layout that leads with the answer. An optional brief puts the verdict, next move, and takeaways before metadata. Supporting sections are built from editorial blocks — headings, short paragraphs, lists, tables, callouts, numbered rules — with tool cards for genuine roundups and ranked "Start Here" picks. A sticky section nav, light/dark toggle (dark default), mobile-friendly layout, clean printing, and reduced-motion support complete the shared shell.

The top bar carries the report's own title beside the logo, separated by a divider — it is how the document names itself before the hero does, so it is worth setting. The bar scrolls away with the page rather than pinning, so it never spends viewport height for the whole read; the section nav below it is the one bar that stays pinned. Use docTitle (short, plain text, no markup); omit it and it falls back to brandSub, then to "Report".

The "Start Here" picks jump to the tool they recommend. Give each topPicks entry a ref naming the exact name of the card it points at (or a section id) and that pick becomes a link: clicking it scrolls to the card and rings it, so the reader can see where they were sent. Fill this in — a pick's title is usually editorial ("IP Clearance (free)") and does NOT match the product name on its card ("IP Clearance Before Sourcing"), so without ref a link is inferred only when the two happen to be identical. A pick that resolves to nothing renders unlinked rather than guessing.

A curated "Branded Research Report" Super Prompt ships in the built-in catalog: launch it, say what to research, and the session researches the topic and hands back a finished branded report link.

How it behaves

Styles — read it, or present it

The template ships as a catalog of named styles rather than a single fixed page. There are three:

• Aurora — the Omniscio house style, dark by default, editorial body, sticky section nav. A page you READ: scroll it, search it, skim it, print it. The right answer unless you have a reason otherwise, and what you get if you ask for nothing.
• Deck — the same report as full-screen slides. One idea per slide, arrow keys, an overview index, a blank screen for when the room should be looking at you. Reach for it when someone will PRESENT the findings rather than read them.
• Book — a plain reading page: one column, one font, light by default with a dark mode, and exactly four text styles (page title, section title, sub-heading, body) in one text colour. Reach for it when the report should read like a clean printed document rather than a branded showcase. It stays tidy whatever you write, because the page — not the author — decides every size, weight and colour (see "Writing for a good-looking page" below).

Deck takes no extra work and no different data. It reads the same report object Aurora reads and works out the slides from what is already there — a section becomes a chapter divider, a quote block becomes a full-bleed quote, a numbered rule list becomes one slide per rule, a table stays a table and splits across slides if it is long. So a report you have already written becomes a deck by asking for one, and the same report can be both.

You can also NAME the slide you want. Inference is the default and it is usually right, but a block may carry a layout when you have something specific in mind. Four to choose from, each reading data the report already has:

layout	What it gives you	Put it on a block with
bignum	ONE figure at the size of the room, with its label and an optional line of context.	stats — the first entry is the figure. Use it when one number matters more than the rest; the stat GRID is for comparing several.
compare	Two panels of equal weight, side by side.	kv with exactly two entries — before and after, ours and theirs, the claim and what happened.
timeline	The entries hung off a rail, so the eye reads the ORDER first.	kv or list, two to six entries. Use it when the sequence is the point, not the items.
matrix	Four quadrants, with optional axis labels via axes: ["Effort →", "← Impact"].	kv with exactly four entries — impact against effort, likelihood against cost.

A layout is a hint about presentation, never a new schema: it is honoured only when the block actually carries the data that structure needs, and a name that is unknown or does not fit falls straight through to the inferred slide. So a typo can cost you the structure you wanted; it can never cost you the slide. Give the block an h as well and it keeps its own heading — without one it inherits the section's name, and the deck then drops the heading rather than printing the same words twice.

It is navigable the way any presentation is: arrows, space, page up and down, Home and End, F for fullscreen, O for the overview, B or W to blank the screen, a slide number then Enter to jump, and ? for the full list. On a phone you swipe. Ctrl+P prints one slide per page. A link ending #7 opens on slide 7.

Ask for a style with an optional style alongside your data. Omit it and you get the default, so nothing written before the catalog existed needs to change. GET /report-template/styles lists every style with a one-line note on when to reach for it, so an agent can pick at runtime instead of reading source. An unrecognised name is refused, naming the valid ones — a typo never quietly produces a report in a style you did not choose.

Re-publishing an existing report with its updateToken and a different style re-renders it in the new look at the same link. Restyling something you already shared does not mint a new URL or strand the one people have.

Adding a style is deliberately two mechanical steps — drop a self-contained HTML file carrying the splice markers into resources/report-template/styles/, add one row to REPORT_STYLES — and a build guard fails if you do one without the other. Which standard to use in the first place, and the full add-a-style walkthrough, live in the agent-facing report-standards guide.

The standard reading order

For a report, recommendation, or proposal, use headline → verdict → next move → takeaways → supporting detail. Keep the headline short, the verdict to two sentences, and aim for three one-sentence takeaways. Put the conclusion and any decision before metadata. Never hide critical caveats inside a collapsed section.

action is readable next-step text, not an executable button. Omit it when nothing needs doing. Brief values and section prose are plain text; HTML-looking strings render literally. The older rich-text fields (the title, section titles and subs, card and pick text, next steps, the footer) still accept a little HTML — bold, italic, code, the gradient <span class="g"> and a line break <br> — in every style; any other tag shows as literal text, so markup carried in from elsewhere can never run on a published page. Omitting brief preserves the previous report layout.

How to write the body — the house style

A report is a document someone reads, not a dashboard of summary tiles. It fails in two opposite ways, and both are fatal: a wall of undifferentiated text, or real detail crushed into one-line cards until the report says nothing.

• Keep the detail. Never compress an explanation into a card blurb to make it fit a shape. Long is fine; unreadable is not. Twenty rules with reasoning stay twenty rules with reasoning.
• Break it up instead. A heading every 150–250 words. Paragraphs of two to four sentences, one idea each. That — not deletion — is what makes length readable.
• Use the block that matches the content. Prose that is really a table reads as a wall of text; an argument crammed into cards reads as nothing at all.
• Nothing important hides. A reader should be able to scroll the whole report without clicking. collapsible: true is for an appendix, never for a finding, a decision, or a caveat.

Writing for a good-looking page

A style owns every size, weight and colour, so the only things an author controls are the words and the structure. These habits are what make a report look good in any style, and they are what Book is built around:

• Short headings. Section titles of two to six words; a page title under about ten.
• Answer first. A one- or two-sentence verdict, one next move, three one-sentence takeaways — never more than four.
• A heading every 150–250 words, paragraphs of two to four sentences.
• The block that matches the content. Comparisons in a table (four columns at most), term and meaning in kv, a sequence in an ordered list, numbered findings in rules.
• Three figures at most in a stats row, each label two or three words.
• One callout per section at most — several in a row cancel each other out.
• Bold for a run-in label at the start of a list item, nowhere else. Book renders italic upright, so never rely on it to carry meaning.

How Book enforces its four styles. Every element the renderer can emit maps onto title, section title, sub-heading or body: bold reuses the sub-heading weight, links are body text with an underline, and code is the one family exception, at body size. The older rich fields accept only the small vocabulary above, so a stray tag shows as text instead of adding a style. The example report inside book.html is itself written to these rules, and a build guard (report-style-book-primitives.test.ts) fails on any size, weight, font or colour outside the declared tokens.

Section blocks

Each section carries blocks — an ordered list of typed blocks. The first recognised key decides what a block is — {"p": "…"} — and the discriminator spelling works too: {"type": "p", "text": "…"} (or "kind") is normalised onto the same block, including {"type":"list","items":[…]}, {"type":"table","columns":[…],"rows":[…]} and {"type":"callout","tone":"warn","title":"…","text":"…"}. A shape neither form recognises renders as a visible "Unrendered block" warning carrying your data, so it is never lost — that warning is your signal to fix the block before anyone reads the report. Every value is plain text: it is escaped first, then a small inline vocabulary is applied to the escaped string (**bold**, *italic*, `code`, [text](url) with http/https/mailto/# hrefs only), so caller data can never introduce a tag the template did not emit.

Emphasis also accepts its HTML spelling — <strong>, <b>, <em>, <i> and <code> render the same as the markdown above, because the example REPORT writes emphasis that way in the legacy title and card desc fields and authors reasonably carry it across. Nothing else does: a <span class="g">, an <img>, a <ul>, or one of those five tags carrying an attribute stays escaped and shows up as literal angle brackets on the page. That is the signal the tag is unsupported — reach for the block type instead.

Block	Shape	Use it for
lead	{ "lead": "…" }	The opening line of a section, one size up
h / h4	{ "h": "…" }	A sub-heading (h3) / a minor heading
p	{ "p": "…" } or a bare string	A short paragraph
list	{ "list": ["…"], "ordered": true }	Enumerations; bold run-ins read well here
kv	{ "kv": [["Term", "Meaning"]] }	Term and definition
table	{ "table": { "cols": [], "rows": [[]], "note": "" } }	Tabular facts and measurements
callout	{ "callout": { "kind": "info|good|warn|stop", "title": "", "text": "" } }	A caveat, a status, a warning
rules	{ "rules": [{ "n": "01", "title": "", "body": [], "violation": "" }] }	Numbered rules, invariants, findings, phases
quote	{ "quote": { "text": "…", "cite": "…" } }	A quotation
stats	{ "stats": [["2.6%", "what it measures"]] }	Headline figures inside the body
code	{ "code": "…" }	Literal text rendered verbatim

A report that uses blocks renders in document mode: one narrow reading column and a document-sized hero instead of the wide marketing splash.

The pinned router

nav is worth filling in on any report with more than two sections. It builds a bar that stays pinned under the toolbar as the reader scrolls, and it takes two forms from the same list:

• Wide screens — a chip rail. The chip for the section you're in lights up and slides itself into view, so the bar always shows where you are.
• Phones — a single row: a dot, the current section's name, 4 / 9, and a chevron. Tapping it opens a numbered list of every section with the current one marked.

A gradient reading-progress line runs along the bottom edge of the bar, so a long report shows how much is left. With no nav entries the bar is removed entirely rather than pinned as an empty band.

Give each entry an id that matches a section id:

"nav": [{ "id": "why", "label": "Why" }, { "id": "rules", "label": "The 20 rules" }]

{
  "docTitle": "Documentation taxonomy",
  "title": "One question per doc.",
  "brief": {
    "verdict": "Every document answers one question and names one real feature it serves.",
    "action": "Fix the roadmap board first, then land the shared schema.",
    "takeaways": ["Three vocabularies collapse into one tree.", "Nothing moves on disk."]
  },
  "nav": [{ "id": "why", "label": "Why" }],
  "sections": [
    {
      "id": "why",
      "icon": "database",
      "title": "Why this exists",
      "blocks": [
        { "lead": "A document nobody can place is a document nobody maintains." },
        { "p": "The link the whole system depends on exists on **0.6%** of nodes." },
        { "h": "Measured on the live corpus" },
        { "table": { "cols": ["Family", "Files", "Anchored"], "rows": [["Contracts", "1,327", "35"]] } },
        { "callout": { "kind": "warn", "text": "Figures were measured, not estimated." } },
        {
          "rules": [
            {
              "n": "01",
              "title": "A document answers exactly one question",
              "body": ["A document that answers two questions is two documents."],
              "violation": "A contract that explains how the code works."
            }
          ]
        }
      ]
    }
  ]
}

Cards (items) still exist and are right for a genuine roundup of comparable things — one tool per card, one vendor per card, each with a cost badge and source link. They are the wrong home for an argument, a rule, or an explanation.

Guarantees

• The fill-in markers appear exactly once each — build-guarded, and the server-side renderer re-verifies them at render time, so a splice can never hit the wrong spot.
• Rendered data is escape-hardened: report data can never break out of the page's script element, no matter what strings it contains.
• The template is self-contained (embedded logo; only Google Fonts load externally) and safe for the Shares mobile sandbox (no bottom-pinned fixed elements).
• The render route reuses the canonical share-publish pipeline (same limits, expiry defaults, short-link and update-in-place semantics); the GET route is read-only with no parameters; errors are humanized.

Contract: report-template-contract. Tests: presentation (reading order, literal prose, disclosure navigation, print-state restoration, and legacy compatibility), template integrity (lint lane), the pure renderer (escape + marker re-verification), shim shape + port-agility, prompt-bundle gating, and a live-server integration suite (auth, content, one-step render + publish).

For agents

How it works (agent mechanics)

• The template is a bundled asset shipped with the app (resources/report-template/), so it exists on every install and versions with the product — zero setup.
• Preferred path — one-step render: the agent builds ONLY the report data (a JSON object) and POSTs it to http://127.0.0.1:19519/report-template/render with the standard AMC_CLI_TOKEN bearer — body { data, title?, label?, expiresIn?, shortLink?, updateToken? }. The server splices the data into the bundled template (the AI never touches the HTML shell, so a malformed page is impossible) and publishes the result to Shares through the same pipeline as /share/publish, returning the share URL in one step.
• Manual path: GET http://127.0.0.1:19519/report-template returns the raw template (text/html). Its example const REPORT = {...} object between the two marker comments (REPORT-DATA-START / REPORT-DATA-END) documents every field; an agent may replace only that block and publish the file itself. Optional blocks (brief, chips, stats, top picks, next steps, footer) may be omitted and the page still renders cleanly.
• Every non-SSH spawned session receives this guidance automatically via the standing [ BRANDED REPORT TEMPLATE ] instruction (same delivery as the Shares/convert/download capabilities); SSH sessions are excluded because they cannot reach the local server.

Related

• shares-view.md — where a published report appears once a reader opens it.
• artifact-sharing.md — the Shares pipeline this template publishes through.
• share-artifacts.md — publishing a file as a public link.