> For the complete documentation index, see [llms.txt](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/ui-surfaces.md). # Trend Finder UI Surfaces This guide explains the browser surfaces that turn the current Trend Finder payload into creator and operator workflows. ## Trends, Hidden Gems, Watchlist These three surfaces are intentionally different. | Surface | Selection Logic | Why It Exists | | ----------- | ----------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | | Trends | Topics that are not hidden gems, sorted by score, then momentum, then evidence count. | Shows the strongest current opportunities with enough broad signal to inspect immediately. | | Hidden Gems | Topics flagged as hidden gems, sorted by continuous gem score, then score, momentum, and novelty. | Separates early, lower-volume signals that may be valuable before they have broad source coverage. | | Watchlist | Generated rows for analyst reasons, hidden gems, rising deltas, strong creator fit, or high novelty with weak evidence. | Creates a short follow-up queue for the next run, so early bets can be checked instead of forgotten. | Important distinction: hidden gems are filtered out of the ranked Trends list. That prevents low-volume opportunities from being buried in the same ranking as broader trends. The Watchlist tab is also not a manual saved-items feature. It is generated from the current run and recalculated on each run. Browser-local pinned topics are a separate Watchlist layer. A pinned row can store a baseline snapshot, bounded note, normalized tags, drift state, last seen time, quality, lifecycle, and score context in localStorage. Those fields help an operator compare the current run with the moment they pinned a topic, but they do not edit generated topics, generated Watchlist rows, score fields, source summaries, static Brief output, or private caches. The Trends tab header includes a compact run-summary KPI strip projected from existing payload data: ranked topics, run mood, active sources, evidence rows, hidden gems, and run freshness. The freshness label is derived from `lastUpdatedAt`; the run mood is derived from movement, action verdict mix, and average saturation. No collector or payload field is added for the strip. The header also includes a polarity/attention grid for the top ranked topics. Each row shows movement, action verdict, `attentionPattern`, and a reception column. Reception renders bounded aggregate-only labels: `endorsed`, `contested`, `ratioed`, `mixed`, or `unavailable`. It is projected from normalized aggregate metrics already present in the payload and never from comment bodies or raw source rows. The Trends dashboard also includes a compact One to Watch strip. It projects existing prediction, Story Log, current topic, reception, and corroboration fields into a short next-cycle watch readout. Rows are ranked deterministically from due state, prediction direction, watch-next/rationale copy, current score, evidence count, source count, reception, corroboration, visibility, generated date, topic name, and stable IDs. It does not run a new prediction model and it does not create a new claim beyond stored prediction records. Generated payload closeout now requires the derived fields these surfaces read: per-topic `attentionPattern`, `receptionSignal`, `corroboration`, and `securityRelevance`, and `evidenceRationales`, plus report-level `runNarratives` and `industryEvents`. Legacy payloads can still parse through schema defaults, but a newly generated collector payload or static Brief export fails before rendering when those branches are missing or wrong-shaped. ## Phase 29 Surface Closeout Phase 29's shipped live surfaces are projections over the existing Trend Finder payload. The Trends header shows polarity, attention, reception, run mood, and compact One to Watch context. Brief and static Brief show richer creator context: today's pick, One to Watch, movement groups, demand centers, industry events, security lens, evidence rationales, source health, spend labels, and calibration context. Sources and Engine Replay show source-death, scheduler, pre-run estimate, and validation/provenance states as bounded labels. Loading, empty, degraded, unavailable, and error states should remain visible instead of blank. Legacy payloads can render explicit fallback labels, but newly generated payloads and static Brief exports must pass required-derived field closeout before they are treated as release-ready. Static Brief archival and richness are local export behavior, not hosted publishing. Generated archive runs, latest pointers, manifests, copied assets, and QA results live under ignored private cache roots unless an operator chooses a separate hosting workflow. The report may link public evidence and copy manifest-approved local assets, but it must not inline social embeds, thumbnails, transcripts, audio, video, iframe content, object embeds, remote scripts, raw source dumps, prompts, provider responses, private paths, local triage notes, account auth, or token-shaped strings. The UI does not claim podcast themes or broader social reach as shipped. Podcast/audio remains deferred by the Session 16 compliance decision, and X/Twitter, TikTok, Instagram, and Bluesky remain non-goals under the current source posture. ## Tab Purposes | Tab | Purpose | | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Trends | Main signal cockpit. It shows ranked trends, selected trend inspection, score factors, source coverage, evidence, Creator Lens, run control, and runtime diagnostics. | | Workbench | Dense operator table. It scans all generated topics, evidence, source labels, filters, sorting, and browser-local triage annotations from one surface. | | Hidden Gems | Early opportunity surface. It focuses on topics with high novelty and limited source/evidence saturation. | | Sources | Trust and coverage surface. It shows source health, source-role coverage, evidence contribution, scheduler first-run readiness, warning states, and runtime readiness. | | Watchlist | Follow-up queue. It shows why a topic was selected for monitoring, movement, source/evidence context, 12-week history, and prediction/retro rows when available. | | Brief | Creator digest. It compresses the run into today's pick, One to Watch, movement groups, demand centers, industry events, security lens, top creator angles, source health, evidence to verify, prediction/retro context, and opt-in static export. | The Brief tab is the dashboard-native delivery surface. The opt-in static Brief export writes a standalone local report from the same validated generated payload when an operator runs `bun run trend-finder:export-brief`. The static export runs the same required-derived-field closeout before projecting report rows, so the standalone Brief cannot polish a stale payload that lacks required attention, reception, corroboration, security relevance, evidence-rationale, or run-narrative/industry-event branches. The Brief tab renders a fuller One to Watch section from the same shared view-model as the Trends strip. Rows show direction, due state, watch-next copy, rationale, support labels, caveats, cited evidence IDs, and calibration honesty. Missing current topic context stays visible as support unavailable. Missing calibration renders `Uncalibrated` or `Accuracy unknown`; the UI never shows a per-row hit-rate or mock accuracy chip. If aggregate calibration has resolved retros, it appears only as context for the section. The shipped Action Queue is the Brief tab's Decisions section plus the Workbench decision queue preset. It groups the same deterministic action verdicts into Act now, Monitor, Review, and Ignore. There is no standalone Action Queue route in Phase 28. Visibility bands and suppressed-noise controls are presentation filters over generated topic quality. Trends hides suppressed and rejected rows by default behind a summary/control, while Workbench can still inspect those rows by band or noise risk. Visibility controls never remove payload rows or change collector behavior. ## Search Palette Trend Finder has an extension-local command palette over the already-loaded browser payload. It opens from the Trend Finder shell with Ctrl/Cmd+K or `/` when focus is not inside an input, textarea, or contenteditable region. The palette searches projected, display-safe text only: * topic names, canonical IDs, slugs, aliases, theme labels, and theme keywords * source names, source IDs, source roles, and quality labels * evidence titles, snippets, topic labels, and source labels * creator angles, contrarian angles, suggested titles, and hooks Scope controls filter results to all records, topics, sources, evidence, or angles. Result sets are bounded and deterministically ordered. Topic-owned results navigate to `/extensions/trend-finder/trends#topic:` so the Trends view can select the matching topic through its existing hash re-entry logic. Source-owned results navigate to the Sources tab. Ranking is browser-only. The palette first uses lexical scoring, then attempts transient Web Crypto feature-hash vectors over the same loaded strings. If Web Crypto is unavailable, a query becomes stale, or vector ranking times out, the palette keeps the lexical results and shows a fallback state. It never fetches new remote data and never stores vectors in generated payloads. ## Signal Workbench Signal Workbench is the table-first review surface for repeated local triage. It renders every generated topic, including hidden gems and watchlist-selected topics, in one sortable workbench. Rows show score, momentum, novelty, continuous gem score, saturation, evidence count, movement, lifecycle, source diversity, top source role, builder signal, corroboration status, risk flags, security severity/action chips, sparkline state, published date, relative source-local lift, theme, outlier idea state, asset availability, and local triage or watching state. The Workbench can search across topic names, summaries, creator angles, hooks, audience questions, evidence titles, evidence snippets, and source names. Its filters cover source role, data provenance, movement, hidden-gem state, score band, source-local actionability band, security severity, runtime or fallback state, source health, asset availability, and triage state. Sortable columns include score, momentum, novelty, evidence count, movement, source diversity, source role, published date, relative lift, security severity, and triage state. Sorting uses deterministic tie-breakers so rows with matching values keep a stable order by rank, score, topic name, and topic ID. Expanded rows show supporting evidence with public links when available, source labels, snippets, relevance and source-local chips, source health, warning labels, security severity/action chips, and browser-safe asset availability fallback labels. Security actions are informational labels such as review exposure, monitor advisory, validate guardrails, check dependency chain, track policy change, or review privacy controls. Missing evidence, missing snippets, unavailable links, unknown health, unavailable source-local baselines, unavailable security relevance, and missing assets render explicit labels instead of blank cells. Workbench triage is local browser state only. The local states are `acted-on`, `ignored`, `revisit`, and `watching`, with an optional bounded note per topic. Triage persists in localStorage under `ai-os.trend-finder.signal-workbench.v1`. The storage parser drops malformed rows, invalid states, empty topic IDs, duplicate overflow, and oversized notes. Workbench triage and watching do not edit generated topics, source summaries, score fields, generated Watchlist rows, static exports, source caches, logs, provider responses, prompts, Actor inputs, Dataset rows, credentials, or local file paths. The generated Watchlist tab remains generated from the current run; browser-local watching is a separate presentation filter for Trends, Hidden Gems, and Workbench. Workbench can group rows by theme. Theme labels can come from validated analyst output or deterministic fallback grouping. The grouping summary shows topic count, top score, outlier count, outlier idea count, and provenance. The model-backed embedding path remains rejected by ADR 0002. The shipped fallback uses dependency-free feature-hash similarity and Creator Lens focus overlap. The cross-source outlier preset filters to topics with available source-local outlier evidence and sorts by relative lift. The preset uses the existing reviewed source-local baseline model across supported sources. Per-outlier creator ideas appear only when the top-N outlier enrichment or deterministic fallback created bounded copy for an evidence row. ## Visibility Controls Each Trend Finder creator tab has a visibility menu for local presentation filtering. It can hide and restore supported panels, topics, source rows, evidence cards, score factors, source breakdowns, source-role rows, and source contribution rows depending on the active tab. Visibility does not edit generated data, source caches, watchlist generation, scores, or collector behavior. It only filters what the current browser view renders. Settings persist in browser localStorage under `ai-os.trend-finder.visibility.v1`. Older compatibility keys can be migrated. The local dev server can also read an optional `data/trend-finder.visibility.json` file through the loopback-only `/__trend-finder-visibility-config` endpoint. The file overlay returns parsed hidden IDs and warnings only; it is not a secret or runtime data channel. ## Signal Radar Signal Radar is the selected-topic inspection surface in the Trends tab. It combines the selected topic's score, movement, lifecycle, aliases, convergence, score trajectory, source breakdowns, evidence links, score factors, creator angle, hooks, and questions. The radar map now plots generated topics with meaningful axes. X is momentum. Y is inverse saturation when saturation is available, otherwise novelty, with a fallback band when neither value is available. Bubble size is based on evidence count, and lifecycle stage controls the radar color. The selected topic is highlighted, and selecting another bubble changes the inspected topic. The animated coordinates, frequency, and lock labels remain visual HUD state. They are not an external scan, real geolocation, radio telemetry, or source collection proof. Missing momentum, saturation, or novelty renders explicit fallback labels instead of guessing positions. ## Evidence To Verify "Evidence to verify" means "the public evidence links behind the generated claim." It is deliberately phrased as verification because the generated analysis is not a source of truth by itself. An evidence record can include: * title * source ID and source name * public URL when available * snippet * published timestamp * relevance score * source metrics such as points, comments, downloads, stars, forks, upvotes, or views Topic views show evidence linked through `topic.evidenceIds`. Brief shows the top evidence links sorted by relevance score. If a topic references an evidence ID that is missing from the generated payload, the UI renders it as missing evidence instead of inventing a link. Use this section to check whether the source actually supports the summary, creator angle, or watchlist decision before acting on it. ## Evidence Asset Previews Evidence cards can include optional `evidenceAssets` metadata. The UI treats assets as browser-safe metadata first, not as permission to expose media. Each asset has an ID, evidence ID, source ID, kind, status, content type, byte size, created time, provenance label, compliance document path, optional local bridge URL, and fallback label. Current statuses shown in evidence cards are: * `available`: a reviewed local asset can be fetched through the protected local bridge. * `blocked`: a raw source field exists but current compliance does not approve browser exposure. * `unsupported`: the source or asset kind is not approved for previews. * `failed`: validation or bridge checks failed, so the card renders a fallback. * `missing`: the manifest referenced an asset that is not present. * `pruned`: stale private asset state was removed from the active keep set. * `unavailable`: no asset is available for the evidence row. Preview cards use compact fixed dimensions. Available previews are fetched as blobs with the local dev token header; the token is not placed in the URL. Fallback states render labels only. Browser payloads and UI components must not render local filesystem paths, raw source media URLs, transcripts, Actor internals, Dataset rows, or cache roots. ## Source Setup Source Setup appears on the Sources tab beside source health and scheduler readiness. It is a local-only configuration surface for reviewed Apify source declarations, not a public admin console. The panel can show credential presence, private config presence, reviewed source labels, editable target fields, source caps, compliance doc links, safe warnings, and last-run health. It can save only reviewed source IDs and allowlisted target fields through the loopback source setup bridge. Unknown source IDs, unsupported target fields, raw JSON edits, private feeds, private accounts, comment-body collection, and unreviewed historical-window shortcuts remain blocked. Source Setup must not render credentials, private config paths, raw Actor input JSON, Dataset rows, Actor logs, account IDs, auth headers, token-shaped strings, or unreviewed source IDs as editable rows. Saving Source Setup does not run a collection by itself; the operator still uses run control or the scoped scheduler to generate a new browser-safe payload. ## Scheduler First-Run Panel The Sources tab includes the scheduler first-run panel next to source setup. The panel is an operator checklist for making the scoped Trend Finder refresh observable from a fresh local clone. The checklist combines: * extension enablement * credential readiness * reviewed source setup * runtime readiness * source config availability * generated Trend Finder data freshness * run-now availability * latest scheduler status * Engine Replay review availability The panel also shows the current scheduler cadence, timer intent, latest scoped run state, generated-data state, recurring spend projection, and safe diagnostics. Cadence controls are limited to reviewed Trend Finder scheduler candidates. The timer checkbox records local intent; installing or changing a system timer is still a command-line operator step. The panel includes a pre-run estimate block before the cadence controls. It shows estimated next-run cost, cadence projection, wall-clock estimate, and the source basis for the estimate. Loading, error, offline, unavailable, and missing-cost states render explicit labels. The copy says estimate and does not claim a hard cap. The panel can refresh scheduler status, save cadence/timer mutations, and start the same local run action used by Trend Run Control. Busy states disable repeat submits while a load, save, or run is active. Error and offline states are shown in the panel instead of leaving stale status in place. Browser-visible scheduler state is intentionally narrow. The UI can show safe labels, counts, cadence IDs, generated-data timestamps, warning counts, and command hints. It must not show scheduler config paths, raw calendar input, stdout/stderr, raw logs, prompts, provider responses, source payloads, Actor inputs, Dataset rows, credential values, or token-shaped strings. ## Live Run Progress Trend Run Control can show live progress while a local Trend Finder run is active. The progress component uses Engine Replay stage IDs and labels for the current stage and completed stages, plus elapsed time and bounded per-source counts when available. Before a manual run starts, Trend Run Control shows the same pre-run estimate model in compact form on the Trends dashboard and in fuller form wherever the full control is mounted. The estimate sits before the run action and runtime or source readiness details. Scheduler estimate loading, error, offline, and unavailable states do not block the manual run button by themselves; normal duplicate-run and in-flight guards still control the button state. Live progress is a presentation layer over the safe run-status endpoint. It does not stream raw process logs. When progress cannot be loaded, the control falls back to the existing coarse lifecycle labels such as starting, running, completed, skipped, canceled, already running, failed, or unavailable. The same progress summary can appear in compact form inside run controls and as context in Engine Replay. Accessible status regions use polite live updates, native buttons/selects/checkboxes keep keyboard behavior, and unavailable fields render explicit fallback labels rather than blank space. ## Brief Tab Brief is for fast creator action, not deep debugging. It answers: * What is the headline opportunity? * What are the top creator angles? * Which sources are active, degraded, or offline? * Which public evidence should be verified? * Did Trend Finder make or grade any recent near-term predictions? The Brief tab uses: * top three ranked trends * an explicit today's pick from the visible ranked topics * movement groups for rising, cooling, emerging, and steady topics * demand centers derived from question-shaped evidence * industry events derived only from reviewed RSS and Google News evidence that passes the two-publisher rule * security lens rows derived from existing normalized evidence and the reviewed security keyword category * top five evidence links by relevance * source health summary * provenance labels * recent prediction/retro rows, calibration, and Story Log rows when archives are available * run mood and banded posting-window context, paired with calibration labels * polarity/attention rows with movement, action verdict, attention pattern, and aggregate reception labels * angle-pack copy: creator angle, contrarian angle, plain-language explainer, and suggested title * bounded history and sparkline context where available * export QA status for the browser-safe Brief projection * copy actions for Markdown and JSON composed from that same safe projection Brief does not replace Trends or Hidden Gems. It is the "what should I look at or create from this run?" page. Industry events are a cycle-level lens, not a scoring input. Rows appear only when existing `rss-ai-news` or `google-ai-news` evidence clusters across at least two independent publishers. Each row shows bounded event copy, publisher count, provenance labels, related topics, and cited evidence links. If no event passes the rule, Brief and static Brief show an explicit empty state instead of weakening the publisher requirement. The security lens is also display-only. It classifies existing topic evidence for security relevance, severity, reason labels, cited evidence, and bounded informational actions. It does not add a security feed, read article bodies, read comment bodies or transcripts, run dependency scans, execute remediation, or change topic scores. Non-security topics render explicit unavailable or empty states. The Brief export panel is browser-only. It can copy a creator-ready Markdown Brief or a bounded JSON projection to the clipboard. Clipboard writes show success, denied, unavailable, or failed states and disable repeat actions while a write is pending. The copied payload is built from projected display fields and excludes raw prompts, source dumps, private paths, local visibility state, cache keys, and token-shaped strings. ## Static Brief Export The static Brief export is a script-side projection of the generated Trend Finder payload, not a browser read of dashboard state. It renders a local `index.html` report with: * run metadata and provenance labels * source health * top opportunities with score, movement, confidence, evidence, and actionability labels * corroboration labels projected as status/count text only * security lens rows with severity, reason labels, informational action tags, and cited evidence labels * today's pick, movement groups, demand centers, industry events, angle-pack copy, bounded sparklines, and Story Log summaries when present in the generated payload * polarity/attention rows projected from display-safe topic view models, with aggregate reception labels * public evidence links and metric chips * prediction and retro context * spend, enrichment, and asset summaries * fallback labels for unavailable, blocked, unsupported, missing, failed, or pruned evidence assets After render, the exporter runs deterministic QA over the projected report, rendered HTML, and manifest candidate before any output is promoted. QA checks required section markers, source/evidence/decision/security/movement structure, creator-angle sparsity, manifest count alignment, cited security evidence details, and private-string leaks. Blocking QA failures stop the export and leave any previous output directory in place. The final manifest records a compact `qa` object with status, generated time, checked-section count, issue counts, warning counts, blocking counts, and bounded display-safe issue summaries. The export excludes local Workbench triage, per-view visibility settings, hidden IDs, browser localStorage, raw prompts, provider responses, raw source dumps, raw logs, Actor inputs, Dataset rows, raw billing payloads, credentials, account auth, private caches, and local filesystem paths. It also does not preserve the dashboard's interactive visibility menu. The standalone report has only local report interactions: expandable sections and copy buttons for safe public links. The default output root is `.cache/extensions/trend-finder/static-brief/`, which is generated local state and ignored by git. Public hosting is optional operator work; generated reports are not committed or deployed by default. ## Engine Replay Route Engine Replay lives at `/extensions/trend-finder/engine`. It is not one of the five creator tabs. Replay mode renders latest-run proof from the browser-safe `engineTrace` payload. Reference mode renders the committed Trend Finder Markdown manuals with in-app tabs for Concepts, Pipeline, Sources, Runtime, Scoring, Creator Lens, History, and UI Surfaces. Replay mode also shows scheduler context when the generated payload includes it: cadence, timer intent, latest run state, generated-data state, recurring spend projection, and current live progress. This is context only. Engine Replay still reads browser-safe payload fields and never reads private run state files, scheduler config paths, raw logs, prompts, provider responses, Actor internals, Dataset rows, or account auth. Reference mode is a committed-docs view, not a dynamic documentation loader. It imports the registered Markdown manuals through the Reference mode registry, switches registered Trend Finder manual links to the matching tab, and leaves non-registered local docs as code references. It does not read generated reports, private caches, scheduler files, source setup config, raw traces, or local browser pin/note/tag state. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://ai-os-and-trend-finder.gitbook.io/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/ui-surfaces.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.