> 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/concepts.md).

# Trend Finder Concepts

This is the conceptual entry point for Trend Finder, the AI OS extension that turns reviewed public source evidence into creator-oriented trend intelligence.

Trend Finder's main job is not to say "this topic is popular." Its job is to answer a narrower question:

> Which emerging AI topics look early enough, evidenced enough, and useful enough for this creator lens to act on or monitor?

Trend Finder belongs to the `trend-finder` extension, not the AI OS host shell. Use Trend Finder language for extension routes, collectors, sources, evidence, scores, creator angles, watchlists, hackathon docs, and demos. Use AI OS language for the host shell, setup flow, local operator dashboard, package metadata, storage keys, and platform docs. See [Project Identity](/ai-os-and-trend-finder-docs/docs/project-identity.md).

Nothing in these docs should be read as a claim that every named source is always live. A source contributes live evidence only when the current local configuration, credentials, compliance gate, and adapter run actually produce browser-safe evidence. Otherwise Trend Finder should expose fallback, degraded, blocked, fixture/demo, or empty states instead of pretending the signal exists.

## Mental Model

```
Sources -> Evidence -> Topics -> Scores -> Surfaces -> Feedback loop
```

Trend Finder collects public source items, normalizes them into browser-safe and analyst-ready evidence, optionally asks an AI analyst to cluster topics, falls back deterministically when needed, scores topics, renders current creator surfaces, and uses history plus prediction retros to calibrate future runs.

## Document Map

| Document                                                                                                      | Use It For                                                                                                                  |
| ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [Pipeline](/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/pipeline.md)                             | Aggregate run stages, browser payload boundaries, local run control, state locations, and implementation map.               |
| [Sources](/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/sources.md)                               | Built-in adapters, reviewed Apify declarations, configured sources, source caps, health, and trust/provenance.              |
| [Runtime and Provenance](/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/runtime-and-provenance.md) | AI analysis, deterministic fallback, validation, runtime readiness, provenance labels, and Engine Replay states and modes.  |
| [Scoring](/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/scoring.md)                               | Score factors, derived signals, velocity dynamics, hidden-gem scoring, risk flags, and watchlist rules.                     |
| [Creator Lens](/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/creator-lens.md)                     | Lens fields, competitors, default profile, save/rerun behavior, and how the lens affects AI and fallback output.            |
| [History](/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/history.md)                               | Topic identity, movement, daily series, predictions, target-date retros, calibration, Story Log, and script-only backtests. |
| [UI Surfaces](/ai-os-and-trend-finder-docs/docs/extensions/trend-finder/ui-surfaces.md)                       | Trends, Workbench, Hidden Gems, Sources, Watchlist, Brief, Signal Radar, visibility controls, and evidence verification.    |

## Core Objects

| Object               | What It Means                                                                                                                                                                  |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Source               | A source summary emitted by a built-in adapter or configured reviewed Apify source. Static declarations are metadata, not proof that the source ran.                           |
| Browser evidence     | A normalized source item that can be rendered in the UI. It has an ID, title, source ID, public URL when available, timestamp, metrics, and relevance score.                   |
| Analyst evidence     | The browser evidence shape plus source name and source role, prepared for AI analysis and deterministic scoring. It is deduped and capped before analyst input.                |
| Topic                | A clustered AI trend opportunity with score, evidence IDs, source coverage, summary, why-now, creator angle, hooks, and questions.                                             |
| Canonical topic ID   | The stable identity Trend Finder tries to preserve across runs when a topic is renamed, reclustered, or matched through history.                                               |
| Score factors        | The six 0-100 dimensions used to produce the overall opportunity score.                                                                                                        |
| Creator Lens         | The local audience/format/focus/goal/risk profile used to tailor analysis and creator value.                                                                                   |
| Ranked trend         | A non-hidden-gem topic sorted for current priority.                                                                                                                            |
| Hidden gem           | A low-volume, high-novelty topic that passes strict thresholds and is ranked by a continuous hidden-gem score.                                                                 |
| Watchlist row        | A generated follow-up item for topics that deserve another look next run. It is not a manual bookmark list.                                                                    |
| Watching state       | Browser-local presentation state for keeping a topic visible in this browser. It is separate from generated Watchlist rows.                                                    |
| Brief                | A compact creator-facing digest assembled from the current ranked topics, source health, evidence, and prediction loop.                                                        |
| Lifecycle stage      | A deterministic maturity label: `unknown`, `whisper`, `builder`, `creator`, or `saturated`.                                                                                    |
| Convergence          | Deterministic timing summary for when multiple linked sources picked up a topic within a bounded window.                                                                       |
| Demand cluster       | A group of question-shaped evidence and related topics, with observed counts and labeled estimates only.                                                                       |
| Theme                | A grouping label above topics, from validated analyst output or deterministic fallback token similarity.                                                                       |
| Angle pack           | Creator-facing copy bundle with creator angle, contrarian angle, plain-language explainer, and suggested title.                                                                |
| Outlier idea         | Bounded creator idea attached to top source-local outlier evidence, produced by AI or deterministic fallback.                                                                  |
| Prediction and retro | A feedback loop that predicts next-run direction, then grades older predictions after later runs.                                                                              |
| Visibility setting   | A local presentation preference that hides or restores specific panels, topics, sources, evidence links, score factors, and contribution rows without changing generated data. |

## Surface Summary

| 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 momentum, then score, then 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.             |
| Brief         | Compact digest from today's pick, movement groups, demand centers, current ranked topics, source health, evidence, and prediction/retro context. | Turns the run into creator-facing next actions.                                                                  |
| Sources       | Source health, source-role coverage, evidence contribution, warning states, and runtime readiness.                                               | Shows whether the run is grounded in broad coverage or partial/fallback data.                                    |
| Engine Replay | Browser-safe latest-run trace summaries plus Reference mode docs.                                                                                | Explains proof/debug stages and renders manuals without exposing raw prompts, logs, or private source internals. |

## Common Confusions

| Confusion                                      | Clarification                                                                                               |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| "Momentum" vs "Movement"                       | Momentum is a score factor. Movement is a previous-run delta/status.                                        |
| "Score signal" vs "Score factors"              | They are the same `scoreBreakdown`, rendered in different tabs.                                             |
| `sourceDiversity` vs source diversity factor   | `topic.sourceDiversity` is a source count; `scoreBreakdown.sourceDiversity` is the 0-100 score factor.      |
| "Hidden gem" means weak                        | False. It must pass minimum score, novelty, and evidence thresholds. It is low-saturation, not low-value.   |
| "Watchlist" is manually saved                  | False. It is generated and read-only in the current implementation.                                         |
| "Watching" changes the generated Watchlist     | False. Watching is browser-local presentation state only.                                                   |
| Creator Lens changes current results instantly | False. Edits affect collector output after save and rerun.                                                  |
| Demand Centers are audience-size claims        | False. They use observed question evidence and labeled estimates; they do not invent asker counts.          |
| Theme grouping requires embeddings             | False. The shipped fallback is dependency-free local token similarity; embeddings are deferred by ADR 0002. |
| Radar coordinates are geolocation              | False. Radar axes are topic momentum and openness/novelty, while HUD labels remain visual presentation.     |
| Evidence to verify is optional decoration      | False. It is the source material that should be checked before acting.                                      |
| Brief is a full report                         | False. It is a compact operational digest from the current payload.                                         |
| Prediction/retro is a UI flourish              | False. It is a calibration loop for near-term trend calls.                                                  |
| Visibility changes rerun Trend Finder          | False. Visibility settings are local presentation filters; they do not change collector output.             |
| Engine Reference is runtime evidence           | False. Reference mode renders documentation; Replay mode renders latest-run proof.                          |


---

# 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/concepts.md?ask=<question>&goal=<endgoal>
```

`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.