Briefings and rendered output
The briefing and output layer turns ranked research evidence into useful artifacts. It supports saved daily and weekly watchlist briefings, agent-facing data, terminal Markdown, production briefs, comparison views, and self-contained HTML. It also carries source health and freshness signals so readers can judge what a report supports. This layer is the output part of research skill execution and connects to research planning and querying and research quality and ranking.
Output lifecycle
The system has two related paths. The briefing path assembles findings already stored for watchlist topics. The rendering path turns a current structured report into a view for a person, an agent, a downstream script, or a shared page.
flowchart LR
A[Research report] --> B{Output entrypoint}
B --> C[Terminal or Markdown view]
B --> D[JSON contract]
B --> E[HTML artifact]
B --> F[Context handoff]
B --> G[Production brief]
B --> H[Comparison view]
B --> I[Discovery brief]
B --> J[Library search]
E --> K[Optional hosted page]
L[Stored watchlist findings] --> M[Daily or weekly briefing data]
M --> N[Saved briefing archive]
The central Report is the shared boundary. It carries the topic and time window with ranked candidates, evidence clusters, source outcomes, freshness checks, and optional local-library context. Renderers can remove private local evidence before they create agent or hosted output. References: skills/…/schema.py• L247-267, skills/…/last30days.py• L457-492
Briefing generation
The briefing entrypoint at skills/…/briefing.py builds structured briefing data from the local research store. A daily briefing covers enabled watchlist topics and recent findings. A weekly briefing compares the current seven-day period with the prior seven days and selects the highest-engagement findings for each topic.
The result is data for synthesis rather than finished prose. A topic record can include new counts, the last run state, staleness, its top finding, and failure information. Empty watchlists and fully paused watchlists return explicit states instead of an empty success-shaped report. Both weekly windows use the store's shared finding query, so the comparison follows the same filtering rules as other stored research. References: skills/…/briefing.py• L32-139, skills/…/briefing.py• L142-203
Saved briefing data is archived by date under the local briefing directory. The show command reads a daily file first and then checks the weekly name. This makes briefings reusable without repeating research. References: skills/…/briefing.py• L206-229
Render entrypoints
The rendering layer exposes distinct entrypoints because each consumer needs a different amount of context. Compact output is a synthesis aid. Context output is a small handoff. Brief output is a production shape. Full output keeps the complete evidence dump for saved artifacts and diagnosis. Discovery and library search have their own short views. Comparison entrypoints keep evidence separate for each entity.
| Entry point | Main purpose | Shape of output |
|---|---|---|
render_compact | Human or agent research response | Synthesis envelope, ranked evidence, coverage, freshness, and pass-through footer |
render_full | Durable or diagnostic evidence record | All ranked clusters, all source items, source detail, coverage, and optional footer |
render_context | Small context handoff | Topic, intent, top clusters, source links, warnings, and freshness information |
render_brief | Downstream scripting or production work | Storylines plus optional hooks, tensions, audience questions, and source clusters |
render_for_html | Shareable single-report artifact | Clean Markdown input for self-contained HTML, with metadata and footer |
render_comparison_multi | Multi-entity research response | One evidence section per entity plus a comparison scaffold |
render_comparison_multi_context | Multi-entity context handoff | Per-entity intent, solid clusters, warnings, and resolved-entity context |
render_for_html_comparison | Shareable comparison artifact | Comparison metadata, synthesis, per-entity verification, and footer |
render_discovery | Trending-topic discovery | Topic sections with momentum, engagement, next research command, and coverage notes |
render_library_search | Search of saved research | Dated matches grouped by the topic run that produced them |
The CLI selects a single-report or comparison renderer before it saves or prints output. This keeps comparison output from being mistaken for the leading entity's report. Comparison rendering keeps each entity's evidence and warnings in its own labeled section. References: skills/…/render.py• L107-215, skills/…/render.py• L324-361, skills/…/render.py• L789-1064, skills/…/render.py• L1442-1731, skills/…/last30days.py• L457-535, skills/…/last30days.py• L2318-2365
Briefing data contracts
The structured contracts preserve the difference between evidence, derived ranking, and run health. This lets a downstream reader use the result without treating a missing source or a weak cluster as a finding.
Agent JSON
The default JSON export is a small, versioned handoff. It includes the query, generation time, window length, source states, freshness verdicts, ranked clusters, and candidate results. Each result keeps a title, source, URL, date when known, summary, engagement data, a normalized relevance score, and its cluster position. The current single-topic agent contract is version 1.4.
The raw JSON profile serves a different need. It serializes the full report shape for diagnosis, cache reuse, and internal consumers. The two profiles are not interchangeable: the agent profile is the stable public handoff, while the raw profile exposes the pipeline model. References: skills/…/schema.py• L739-771, skills/…/schema.py• L956-1039, skills/…/last30days.py• L465-472
Discovery JSON
Discovery has its own versioned export because a domain sweep returns topics rather than evidence clusters. The contract carries the domain, window, feed choices, source states, topic rank, momentum, velocity, engagement by source, evidence links, optional content angles, and queue status. Its current export contract is version 1.1, and it does not change the normal agent contract. References: skills/…/schema.py• L876-877, skills/…/schema.py• L1150-1193
Comparison JSON
Comparison JSON wraps one export under each entity label. The top-level result marks the response as a comparison and preserves entity order. Agent-profile comparison payloads carry the same export schema version as single-topic agent payloads.
This structure lets a consumer compare entities without merging their evidence or source health into one misleading pool. References: skills/…/last30days.py• L495-521
Local evidence boundary
Local corpus material is private by default. Agent JSON, terminal evidence, and hosted HTML remove corpus evidence unless the caller explicitly opts in for the JSON export. Drill context and freshness verdicts derived from local corpus material follow the same boundary. Marked public clusters, drill context, and freshness sections remain available for the publishable copy.
When a removed local item shaped a cluster, the report rebuilds the cluster membership and title from the remaining evidence. The output therefore does not retain a private-derived headline after publication. Saved library artifacts apply the same public-section rules when they create a shareable page. References: skills/…/schema.py• L656-873, skills/…/library.py• L111-151, skills/…/render.py• L541-595
Terminal and Markdown output
Terminal output separates material for the hosting agent from material for the final reader. Compact and Markdown output place ranked evidence, statistics, and source coverage inside an evidence envelope. The hosting agent reads this material and writes the final narrative instead of copying the ranked scratchpad.
The renderer searches all clusters that clear the relevance floor when it builds cross-cutting Best Takes and Top Community Comments sections. These sections can surface strong comments from beyond the limited set of clusters shown in the main ranked section.
The output also includes a deterministic footer. It reports populated source lines, top voices, freshness notes, and the saved raw path when one exists. The footer is emitted as a fenced text block so the host can pass it through without changing its tree layout. Full saved output retains every source collected by the run and expresses each item's local rank on the report's 0–100 scale. Source-specific engagement remains visible when a source uses a metric outside the standard display set. Source-controlled titles, actors, and evidence text are flattened and defanged before they enter engine-authored Markdown. Retrieved content cannot create headings, close output envelopes, or open a trusted footer fence. Public section markers also let later library publication retain only content that has passed the privacy boundary. References: skills/…/render.py• L789-948, skills/…/render.py• L439-489, skills/…/render.py• L1803-2013, skills/…/render.py• L2910-2967, skills/…/render.py• L3270-3315, skills/…/render.py• L3936-3978
Terminal report checklist
Compact terminal output can add a short checklist after the canonical report. The checklist gives the host model the rules needed to copy the badge and fenced footer and to format stories, quotes, special digests, and terminal Markdown. It is command-line guidance rather than evidence, so saved Markdown, JSON, HTML, and MCP research output do not contain it. The checklist can be disabled without changing the report itself. References: skills/…/report_checklist.py• L1-11, skills/…/report_checklist.py• L90-219
Evidence states
The renderer treats evidence quality as a display rule, not only a ranking detail. A visible cluster must have a positive score and at least one qualifying member. If no visible cluster clears that floor, the output states that nothing solid was found and suppresses dependent comment and take sections.
Source outcomes remain separate from source silence. A failed, limited, unreachable, or skipped source is shown as partial coverage for synthesis. It must not become a claim that the source had no discussion. Source URLs and retrieved text are treated as untrusted data. Main evidence links allow only safe web destinations, while unsafe or malformed values remain inert text. References: skills/…/render.py• L459-489, skills/…/render.py• L648-676, skills/…/render.py• L1676-1800, skills/…/render.py• L2613-2687, skills/…/render.py• L3936-3978
Production brief
The production brief is a compact Markdown shape for video, scripting, and other downstream work. It always provides ranked storylines and source clusters. It adds narrative hooks from strong fun scores, topic tensions from uncertain clusters, and audience questions from question-shaped titles only when the report supports them.
This mode transforms the ranked report. It does not start a second research pass. It keeps the evidence window and source context while omitting optional sections that have no matching data. References: skills/…/render.py• L2218-2361
Hiring signal output
Hiring signals turn job evidence into a cautious focus signal for research modes that inspect company hiring. The output keeps board-size and rare-role evidence when it survives relevance checks, even when those jobs fall outside the visible ranked candidates. Rejected job evidence remains excluded, and the result is framed as a possible focus rather than an exact roadmap. References: skills/…/render.py• L2296-2399
Source footer
The footer gives the reader a compact account of populated sources and important run metadata. Special source lines can report a source-specific state instead of implying that an empty result means no activity. Meta Ads distinguishes a failed run, an incomplete sample, an unresolved advertiser, and a completed run with no new creatives. Source counts use the correct singular or plural item name, including irregular forms such as story and stories. References: skills/…/render.py• L2802-2993, skills/…/render.py• L2996-3225
HTML rendering
HTML output converts a report into a self-contained page for sharing. The HTML renderer can embed a previously written synthesis verbatim, or it can render selected evidence sections for named audience registers. It adds the version badge, a compact metadata line, the engine footer, and a colophon with the topic and rerun hint.
The conversion removes engine-only material before Markdown becomes HTML. It strips the evidence envelope, invitation text, canonical boundary, and model safety note. Quality warnings remain in diagnostics instead of the shareable page. Public library rendering uses the shared public-markdown filter so local drill, corpus, and freshness sections do not bypass the publication boundary. References: skills/…/render.py• L951-1026, skills/…/html_render.py• L389-435, skills/…/html_render.py• L458-476, skills/…/library.py• L111-151
HTML is self-contained and readable in browsers, print views, and small screens. Markdown links become safe anchors only for allowed web and mail destinations. Other schemes remain plain text. Metadata markers and the fenced text engine footer receive dedicated HTML treatment so they remain visible without becoming active content. Publishable library pages also defuse long digit runs in visible text and link targets before they are hosted. References: skills/…/html_render.py• L371-385, skills/…/html_render.py• L535-553, skills/…/html_render.py• L575-847
HTML synthesis handoff
The HTML request has two user-facing modes. HTML-as-deliverable saves the artifact and gives a short handoff. A normal report plus an HTML copy keeps the normal chat synthesis and adds the saved artifact path. In both modes, the synthesis file contains only the intended prose. The renderer supplies the badge and footer.
For a follow-up save request, the CLI can reuse a fresh structured report cache. The cache avoids a second source fetch while keeping the HTML metadata and footer aligned with the original run. A stale, missing, or different-topic cache causes a fresh run instead. References: skills/…/save-html-brief.md• L5-15, skills/…/save-html-brief.md• L19-77, skills/…/last30days.py• L1196-1309, skills/…/last30days.py• L3327-3374
Saving and publishing
Saving is separate from rendering. An explicit output path overwrites that chosen path. A save directory uses unique names with a date and numeric fallback when needed. Markdown saves keep a full raw evidence artifact, while JSON and HTML preserve their requested wire format.
Saved files use private directory and file permissions when the report contains local corpus evidence. HTML output can be published only after it is rendered and saved. References: skills/…/last30days.py• L281-407, skills/…/last30days.py• L2371-2453
Hosted HTML publishing
Hosted publishing is explicit and optional. The local HTML file is created first. The user then chooses whether to open it, publish it, or stop. A publish request can use a public page or a shared password. The password is passed through a secret environment value rather than exposed in a command line.
The publisher accepts only a successful HTTPS URL from the service. The CLI writes non-secret URL, site, status, and publish-time metadata beside saved HTML. It never stores an update_key, and a publish failure does not erase the local artifact. References: skills/…/save-html-brief.md• L84-122, skills/…/html_publish.py• L27-71, skills/…/last30days.py• L410-454, skills/…/last30days.py• L2454-2504
Research library publishing
The library feed is a separate publishing entrypoint from a single HTML brief. library feed scans saved research, writes a topic-grouped index.html, and writes a local Atom feed.xml. It also creates standalone HTML pages for saved briefs. Publishing the library publishes the brief pages and then an index that links to them. The Atom feed remains local and must be hosted separately for subscriptions.
The library path protects hand-written pages before replacement and prunes only generated orphan pages. Private corpus, drill, and freshness sections are removed from the publishable copy by the shared public-markdown filter, even when the local library keeps them. References: skills/…/last30days.py• L2626-2729, skills/…/last30days.py• L2732-2790, skills/…/html_render.py• L441-524, skills/…/library.py• L111-151
Verification paths
Verification checks the output layer at three levels. Unit tests cover data shape and renderer behavior. CLI integration tests check mode routing and saved artifacts. The verification bundle adds diagnosis, provider smoke runs, latency samples, and an optional judged quality comparison.
Freshness verification is a separate act-time path. It re-checks source-grounded claims and stores verdicts such as current, stale, contradicted, or unsupported. It can verify a fresh report or a still-valid cached report, then updates the cached report without extending its cache lifetime. Hosted backend runs cannot perform this verification. References: skills/…/schema.py• L216-234, skills/…/last30days.py• L1316-1390, skills/…/last30days.py• L3249-3265
The verification bundle runs the full test set and Python compilation before its live checks. Smoke runs inspect provider selection, result counts, and source errors. The evaluator compares baseline and candidate outputs through generated metrics and a summary report. References: skills/…/verify_v3.py• L42-80, skills/…/verify_v3.py• L83-157, skills/…/verify_v3.py• L173-191
Change checklist
When these files or sections are changed, remember to consider these:
- Keep
AGENT_EXPORT_SCHEMA_VERSIONandDISCOVERY_EXPORT_SCHEMA_VERSIONaligned with every single-topic, discovery, and comparison JSON consumer when an export payload changes. - Keep the private-corpus removal boundary aligned across agent JSON, terminal rendering, direct HTML, comparison HTML, and library publication. Include marked public drill, cluster, and freshness sections when local evidence is present.
- Keep
--emit=htmlsynthesis-file behavior aligned with report-cache reuse so metadata, source scope, freshness verdicts, and footer describe the same run. - Keep save-path allocation and footer path display aligned when collision fallback chooses a dated or numbered filename.
- Keep
--publish-htmlseparate fromlibrary feed --publish; they publish different artifact sets and use different local metadata flows. - Keep the freshness verdict states and their rendered table aligned with the verifier and cached-report update path, including public and private verdict partitions.
- Keep
Best TakesandTop Community Commentscandidate scope aligned with the relevance-floor gate when cluster limits or auxiliary ranking changes. - Keep source-error detail out of the user-facing footer while preserving it in partial coverage, saved raw output, JSON, and diagnostic paths.
- Keep single-entity, multi-entity, context, production, discovery, and HTML renderers aligned on the same relevance-floor and private-evidence rules.
- Keep untrusted source URL, title, snippet, actor, and footer-field handling safe in both Markdown output and HTML conversion. Unsafe schemes, forged headings, engine markers, code fences, separator characters, and long digit runs must not become active links or new output blocks.
- Keep the terminal checklist outside canonical output and aligned with the compact report's badge, footer, quote pools, and special digest sections. Its environment-based disable path must not change saved or machine-readable output.
- Keep weekly briefing windows on the shared store query so topic changes do not produce a different view of saved findings.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A visible cluster has no qualifying evidence | Rejected evidence can appear as a finding or feed comment sections | Apply the relevance floor before rendering clusters and auxiliary sections |
| A source fails after returning no items | The report can falsely imply that the source was quiet | Render the source as partial coverage and keep its failure state separate from no-results |
| Strong comments exist only in clusters beyond the visible cluster limit | Best Takes or Top Community Comments can omit useful evidence | Build auxiliary sections from every cluster that clears the relevance floor |
| HTML is generated from a stale or different-topic cache | The synthesis and the metadata/footer can describe different research | Reuse only a fresh cache with the same topic and scope; otherwise run fresh research |
| Local corpus, drill, or freshness evidence reaches a hosted artifact | Private file content or claims can be shared outside the local machine | Remove private blocks and keep only marked public sections at the publication boundary |
| A publish request fails after local save | The user may lose a usable report or assume no artifact exists | Save locally first and report the local path even when hosted publishing fails |
| A synthesized or source URL uses an unsafe scheme or malformed Markdown characters | Opening the shared page can expose an active script, local file link, or broken report structure | Sanitize untrusted URLs and allow only safe link schemes in Markdown and HTML |
| Retrieved text or source-controlled actor data contains headings, engine markers, footer separators, or code fences | Source content can alter the evidence boundary or forge pass-through output | Flatten and defang untrusted text before inserting it into engine-authored blocks and the fenced footer |
| A comparison renderer merges evidence or health across entities | A consumer can attribute one entity's finding or source failure to another | Keep per-entity evidence sections and labeled JSON or HTML comparison blocks |
| Meta Ads retrieval stops early or cannot resolve an advertiser | The footer can imply that no ads exist or that a partial count is complete | Render failed, partial, unresolved, and completed-empty states separately |
| Discovery has only weak or single-source topics | The output can present noise as a trend | Keep the confidence floor and show the closest weak signal as weak |
| A host treats the terminal checklist as report evidence | Checklist guidance can leak into saved or machine-readable output or be mistaken for findings | Append it only as command-line presentation after compact output and keep canonical renderers free of it |
| An export consumer assumes the discovery payload has the single-topic shape | A domain sweep can fail to decode or lose topic-specific fields | Use the discovery kind and schema version as the contract boundary |
Key files
| File | Why to read it |
|---|---|
| skills/…/briefing.py | Daily, weekly, show, and archive briefing data flow |
| skills/…/schema.py | Shared report model, export versions, private evidence boundary, discovery JSON, and JSON contracts |
| skills/…/last30days.py | CLI mode selection, cache reuse, saving, comparison routing, and publishing lifecycle |
| skills/…/render.py | Terminal, Markdown, discovery, library search, context, production brief, comparison, HTML handoff, evidence, coverage, URL safety, and footer views |
| skills/…/report_checklist.py | Optional terminal-only formatting guidance that follows compact output |
| skills/…/html_render.py | Self-contained HTML conversion, public filtering, fenced footer handling, safe links, library pages, and feed index pages |
| skills/…/library.py | Public/private filtering rules for saved research artifacts |
| skills/…/html_publish.py | Hosted HTML request and response contract |
| skills/…/save-html-brief.md | User-facing HTML save, publish choice, handoff, and cache rules |
| skills/…/verify_v3.py | End-to-end verification bundle and quality checks |