Omniscio

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

When an Omniscio agent produces a report deliverable — research findings, a tool roundup, recommendations, an audit, a comparison — the product renders it server-side from plain data into one standard branded report page, so every report published to Shares arrives on-brand and consistent.

On this page

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. A brief puts the verdict, the next move and a two-level summary — a very short TL;DR, then a longer Summary — before metadata, so reading just those gives most of the report. 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

Every style shares the same brand and the same section keys. An Omniscio report shows the all-caps OMNISCIO wordmark beside the orb wherever the style names its brand (a report that sets its own brand keeps its own name), and in every style T goes to the section navigation — Aurora's Contents, Book's Contents list, Deck's slide overview, Midnight's current tab — while J / K step to the next or previous section. The keys never fire while the reader is typing or holding Ctrl, Alt or Cmd, and every style takes keyboard focus on open, so a published report answers them without a first click.

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

  • 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). Its OMNISCIO wordmark is painted in that one ink colour.
  • Midnight — a dark page with a sidebar of tabs, one section open at a time. The brief, facts and top picks become an Overview tab, every section gets its own tab, and the next steps get one too. The Overview opens on the brief, including its TL;DR and Summary. Readers move with Tab / Shift+Tab, the arrow keys, J / K, 1–9, Home / End or a swipe, T puts focus on the current tab, and the page takes keyboard focus by itself inside a published share. Reach for it when a long summary or report is read one section at a time rather than scrolled. It prints every tab, stacks wide tables on a phone, and uses one face only — no typewriter font, code samples included.

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 or T for the overview, J / K for the next or previous slide, 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. The same call also returns markdownStyles — the looks a published .md file can wear (omniscio, the default, and book), each with its own one-line note — so one call answers "which look?" for both a report and a plain document. An unrecognised name is refused, naming the valid ones — a typo never quietly produces a report in a style you did not choose.

Which style an omitted style means depends on which door you came through. On POST /report-template/render it means the person's own saved default — the style they picked from the gear button in the Shares sidebar — and a saved id that a later release removed falls back silently to the catalog default rather than refusing the publish. On GET /report-template (downloading the empty template) it always means the catalog default. GET /report-template/styles reports both as default (the catalog's) and userDefault (the person's), so a caller can tell them apart.

Previewing a style. The picker's Preview button opens a live demo Share of that style, and POST /report-template/demo-shares with { "styleId": "deck" } does the same from the CLI. The demo is published once and reused for 30 days; asking again inside that window answers 201 with the same link and publishes nothing. The reply is { url, publicUrl } and never carries the demo's token, which stays in the app so revoking or deleting that share cleans the cached entry up.

Re-publishing an existing report in place is not available to an agent token: naming the share (shareId, or its deprecated alias updateToken) takes the full-trust CLI token, because an in-place update rewrites the bytes behind an already-distributed public link. The name is the share's public id — the value a publish returns as data.shareId, which is also the link's last path segment — so it identifies the share without authenticating anything; the caller is what the gate checks. To restyle, publish the report again — the new look gets a new link, and the one people already have keeps serving the old look.

Adding a style is deliberately three mechanical steps — drop a self-contained HTML file carrying the splice markers into resources/report-template/styles/, add one row to REPORT_STYLES, and add that file to the reviewed shipping manifest (scripts/lib/production-shipping-manifest.json), regenerating package.json's lists with the scripts:run doorway and shipping:lists --write. A build guard fails on each half: one on a style file that does not match its catalog row, and one on a style the catalog advertises that is on no reviewed shipping route (it would render in a dev checkout and 500 on every install). 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 → TL;DR → Summary → supporting detail. Keep the headline short and the verdict to two sentences. Put the conclusion and any decision before metadata. Never hide critical caveats inside a collapsed section.

The two-level summary — every report carries one

The point of a report is that someone can read a small part of it and get most of the value. So every report opens with two labelled summary levels, shown together near the top in every style (a card in Aurora and Book, a "TL;DR" slide and a "Summary" slide in Deck, the top of the Overview tab in Midnight):

Field Label on the page What goes in it
brief.tldr TL;DR About three very short bullets — the whole report at a glance. Plain text.
brief.summary Summary Five to eight fuller bullets — the longer version, one finding each. Each may open on a bold run-in label (**Cost:** …).
  • Read alone, the two should carry about 90% of the report. Write them last, from the finished body, and make every bullet stand on its own.
  • brief.takeaways is the TL;DR's older name. A report that still sends it shows those bullets as its TL;DR. When tldr has any text, takeaways is ignored — move anything still worth saying.
  • Missing a level never blocks a publish. The render response carries a warning naming what to add (or that takeaways was ignored), so the agent can fix it next time. A level that is present but not an array of plain-text strings is named the same way, because only that shape renders.
  • A long Summary in Deck continues onto a "Summary (cont.)" slide rather than overflowing.

Next steps

next is an optional numbered action plan: { title, steps, note? }. Each step may be written either as an object — { n: "1", title: "…", desc: "…" } — or as the tuple the bundled examples use, ["1", "…", "…"]; every style renders both.

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, then the two-level summary: about three very short TL;DR bullets and five to eight Summary bullets.
  • 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; tapping anywhere outside it, picking a section, or Esc closes it.

The router answers the keyboard too: T opens the phone list (or, on a wide screen, moves focus onto the current chip), and J / K jump to the next or previous section. The keys never fire while the reader is typing or holding Ctrl, Alt or Cmd, and the Contents button's tooltip names the key. A published report takes keyboard focus by itself when it opens, so the keys work without a first click.

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.",
    "tldr": ["One question per doc.", "Nothing moves on disk."],
    "summary": [
      "**One tree:** three vocabularies collapse into one taxonomy every document is placed in.",
      "**No migration:** documents keep their paths; only their frontmatter gains a feature link."
    ]
  },
  "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.
  • The app checks every style file for those markers when it starts — the same test the renderer applies, so a duplicated or reordered marker counts too. If one is damaged, an edited or replaced copy on that machine, or a file that cannot be read, the inbox carries a single card naming the template, and the card clears itself as soon as the file is whole again.
  • It then serves the copy it verified for as long as it runs, rather than re-reading the file on every request — so the files changing on disk underneath a running app cannot break publishing, and nothing unverified is ever filled in. Editing a template therefore takes effect on the next start, not immediately.
  • The styles ship byte-identical into every install: the packaging comment sweep exempts resources/report-template/styles/, so the markers the render depends on survive into the packaged build, and a leak guard refuses internal notes (finding ids, repo paths, dates, our own deployment) in any shipped style.
  • Rendered data is escape-hardened: report data can never break out of the page's script element, no matter what strings it contains. The data is embedded as a JavaScript object literal — its JSON verbatim, with every < rewritten as the six-character < escape. That one substitution is what neutralises </script> and <!--; quotes, &, other angle brackets and backticks need no change and reach the page exactly as written.
  • A title is spliced into the page's <title> element HTML-escaped and literally: the splice uses a replacer function, not a replacement string, so a title containing $&, $`, $' or $$ is shown as typed rather than expanded into part of the document.
  • 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).

Last verified 2026-10-15