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

# Trend Finder Scoring

This guide documents Trend Finder score factors, derived signals, formulas, hidden gem thresholds, and generated watchlist rules.

## Score Factors

Every topic gets six score factors. Each factor is 0-100 and the overall score is the weighted sum, clamped and rounded to 0-100:

| Factor            | Weight |
| ----------------- | ------ |
| Momentum          | 20%    |
| Novelty           | 15%    |
| Evidence strength | 20%    |
| Source diversity  | 15%    |
| Niche fit         | 15%    |
| Creator potential | 15%    |

These categories were chosen to balance six different questions:

| Factor            | Question It Answers                                                              |
| ----------------- | -------------------------------------------------------------------------------- |
| Momentum          | Is attention moving now, not just historically present?                          |
| Novelty           | Is this still early or under-saturated?                                          |
| Evidence strength | Is the signal grounded in relevant, reliable evidence?                           |
| Source diversity  | Is the signal appearing across enough different source and role types?           |
| Niche fit         | Does this match the active Creator Lens audience/focus?                          |
| Creator potential | Can this become useful content, workflow, tutorial, product idea, or experiment? |

The UI labels "Score factors" and "Score signal" both refer to the same `scoreBreakdown` object.

Non-obvious data-shape detail: `topic.scoreBreakdown.sourceDiversity` is the 0-100 score factor. `topic.sourceDiversity` is the distinct source count kept for legacy/display compatibility.

Phase 27 also publishes derived signal fields beside the six weighted factors. These fields help operators inspect why a topic is early, crowded, risky, builder-led, or moving unusually fast. They are bounded display and filtering signals unless this manual explicitly says they add capped score support.

## Phase 28 Scoring Integrity Closeout

Phase 28 keeps the score grounded in observed, reviewed Trend Finder data. The collector first normalizes source identity, removes same-source duplicate rows, and groups cross-source syndicated evidence before selecting scoring evidence. Those dedup decisions affect evidence volume, source diversity, momentum, and trace counters, but they do not delete the browser evidence rows that operators can still inspect.

Per-signal quality is calculated before factor math. Low-quality evidence can remain visible, but scoring caps how much one weak source can contribute. A topic with no usable scoring evidence keeps explicit unavailable or zero states for the affected factors instead of inventing support from display text.

Every scoring run is stamped with the active scoring calibration version. Snapshots, predictions, movement comparisons, and retros can use that stamp to label cross-version comparisons rather than hiding or misreading score changes. The stamp is provenance for interpretation; it is not a seventh score factor.

Bounded derived fields such as signal aging, saturation, quality, visibility, action verdicts, lifecycle multipliers, and source-local actionability explain or cap score movement. They do not introduce unreviewed metrics, source calls, private cache reads, raw source payloads, or Trends-Finderz lifecycle labels.

## Phase 29 Scoring Closeout

Phase 29 adds comparison-derived scoring context without changing the six score factor weights. The new fields are bounded lenses over evidence that already exists in the generated Trend Finder payload:

* `attentionPattern` describes adoption, creator-hype, announcement, discourse, or unavailable attention shape.
* `receptionSignal` describes aggregate-only reception as endorsed, contested, ratioed, mixed, or unavailable.
* `corroboration` separates independent-origin support from raw source count.
* `evidenceRationales` publish bounded "why this item" copy for evidence rows that are actually linked to the topic.
* `securityRelevance`, `industryEvents`, and `runNarratives` add release-time inspection context without adding score factors.

These fields can explain or cap action language, but they do not create a seventh factor, replace evidence strength, or approve new sources. Contested or ratioed reception, originator-only corroboration, research-only evidence, weak evidence, suppressed quality, stale/cooling signal aging, saturated lifecycle, and high saturation can keep a topic below `act_now` even when the raw score is high.

Unavailable states are first-class output. Missing role shares, thin aggregate metrics, absent reviewed identity, unsupported source shapes, missing evidence IDs, legacy payloads, or validation failures produce explicit unavailable or omitted rows. Trend Finder does not infer reception from comment text, invent corroboration from source IDs when reviewed identity is missing, or publish a rationale for evidence that does not support the topic.

Browser-safe rationale language is intentionally short and grounded in cited evidence fields. It must not expose prompts, provider responses, raw source rows, comment bodies, transcript bodies, private paths, raw metrics that were not already normalized, or local triage notes. Weak or ungrounded rationale is omitted from topic rendering instead of being padded with speculative copy.

## Post-Factor Adjustments

Trend Finder keeps the six score factors unchanged and computes `rawOpportunityScore` from the weighted sum above. It then applies ordered, bounded post-factor adjustments to produce the final `topic.score`:

1. Confidence dampener
2. Lifecycle multiplier
3. Topic noise downrank

Each generated topic publishes these rows in `scoreAdjustments`. Rows are browser-safe and bounded:

```
{ key, label, delta, kind, detail?, multiplier? }
```

The public PRD contract `{label, delta, kind}` is always present. `key` is a machine-readable enum for deterministic ordering, `detail` is bounded display text, and `multiplier` is present only when the row came from multiplier math. The sum of row deltas equals `topic.score - rawOpportunityScore` after rounding.

Compatibility fields remain available for older consumers:

| Field                     | Meaning                                                                 |
| ------------------------- | ----------------------------------------------------------------------- |
| `rawOpportunityScore`     | Six-factor weighted sum before post-factor adjustments.                 |
| `sampleConfidence`        | Bounded 0-100 confidence based on scoring evidence and source coverage. |
| `confidenceDampenerDelta` | Legacy confidence dampener delta, also represented as a named row.      |
| `topicNoiseDownrank`      | Legacy topic-noise downrank amount, also represented as a named row.    |
| `scoreAdjustments`        | Ordered named rows that explain the raw-to-final score gap.             |

Legacy payloads that omit `scoreAdjustments` parse to an empty array.

### Confidence Dampener

Confidence dampening protects high raw scores from thin scoring samples. It uses `sampleConfidence` and the existing dampener floor to compute a multiplier between the floor and 1.0. The row label is `Confidence dampener`; positive boosts are not emitted by this row.

### Lifecycle Multiplier

Lifecycle now feeds back into ranking through a narrow multiplier, without adding a seventh score factor. The multiplier is keyed to the existing Trend Finder lifecycle stage plus `signalAging.status` and is clamped to 0.85-1.05.

Fresh or active builder/creator signals can add a small lift. Saturated, cooling, or stale combinations can add a bounded penalty. Missing or malformed lifecycle and aging inputs are neutral. Trend Finder continues to use only its own lifecycle vocabulary: `unknown`, `whisper`, `builder`, `creator`, and `saturated`.

### Topic Noise Downrank

Topic quality still computes `topicNoiseDownrank` from bounded quality, clarity, noise, and visibility inputs. The named row records the actual score movement caused after lifecycle adjustment. In fallback mode, the row delta also captures the existing high-noise and watch caps when those caps reduce the final score further.

### Non-Goals

Post-factor adjustments do not add source adapters, network calls, storage paths, analyst calls, dependencies, credential flows, or admin write surfaces. They do not change the six factor weights and do not introduce Trends-Finderz lifecycle labels into Trend Finder payloads or UI.

## Score Factor Details

Score factors use analyst-ready evidence linked through `topic.evidenceIds`, then selected for scoring after quality filtering. Browser evidence can still be displayed even when some of it is excluded from scoring. Low-quality evidence is capped before factor calculation. If a topic has no scoring evidence, Trend Finder sets momentum, evidence strength, and source diversity to zero, while still preserving novelty, niche fit, and creator potential from the analyst or fallback topic.

### Momentum

Momentum is not the same as the movement delta from the previous run. In the ranked trend card, the "Momentum" tile is the 0-100 momentum factor.

When scoring evidence exists, momentum is:

```
recency * 35%
+ engagement * 25%
+ evidence volume * 20%
+ velocity signal * 15%
+ historical momentum * 5%
```

Recency uses source-role half-life freshness at run time. A five-day-old research item decays more slowly than a five-day-old discussion item because the scoring evidence keeps its reviewed source role. Source declarations may provide a bounded `halfLifeHours` override; otherwise the role defaults are:

| Source Role | Default Half-Life |
| ----------- | ----------------- |
| discussion  | 96 hours          |
| news        | 120 hours         |
| developer   | 168 hours         |
| launch      | 168 hours         |
| creator     | 240 hours         |
| research    | 504 hours         |

Half-life overrides must be integer hours from 24 to 720. Invalid timestamps keep the legacy neutral recency fallback of 35.

Engagement is log-scaled across supported public metrics such as points, comments, downloads, stars, star gain, forks, upvotes, and views. Missing metrics contribute zero. Evidence volume is also log-scaled and reaches its cap around eight evidence items.

Velocity signal compares current evidence count to the previous matched topic. New topics with evidence start at 65. Existing topics use `50 + evidence_delta * 12`, clamped to 0-100.

Historical momentum uses the 12-week historical summary when available: latest/baseline score, slope, and recurrence all contribute.

Velocity dynamics add three bounded support signals:

| Signal       | Meaning                                                                                                                     |
| ------------ | --------------------------------------------------------------------------------------------------------------------------- |
| Acceleration | Current evidence-count delta minus the previous evidence-count delta. It needs at least two consecutive deltas.             |
| Significance | Current delta compared with historical delta mean and variance. It needs at least three historical snapshots and variance.  |
| Burst        | Share of the 14-day daily evidence-count series that landed in the most recent two days. It needs a non-empty daily series. |

Acceleration and significance are explanatory signals. Burst can add at most 4 points to the momentum factor through capped support. Missing history, low-sample history, zero variance, missing daily series, and no-volume series are explicit unavailable states; Trend Finder does not invent velocity math when the history is too thin.

Demand enrichment is metric-only. Optional Google Trends demand rows normalize into internal demand signals and can add a bounded momentum lift when the query matches a scored topic. These signals do not create browser evidence, analyst evidence, source diversity, source breakdowns, or public metric chips because Google Trends rows are not canonical public evidence links. The live collector is opt-in through `FINDTREND_GOOGLE_TRENDS_DEMAND_ENABLED` and is documented in `docs/sources/source-compliance-google-trends-demand.md`.

Source-local lift is a second bounded support signal. When a reviewed source exposes a stable public source entity and enough organic evidence for that entity, Trend Finder compares the current evidence metric to the entity median:

```
sourceLocalRatio = current_metric / median(peer_entity_metrics)
```

The baseline excludes reliable pinned, stickied, promoted, sponsored, or ad-like rows. Low-sample, missing-entity, missing-metric, unsupported-source, placement-excluded, and missing-baseline cases are explicit unavailable states, not invented ratios. A row needs at least three peer baseline values after the current row is excluded; otherwise the UI shows low sample. Available ratios are capped at `8x` before scoring support is calculated. That capped support can add at most 4 points to momentum, 4 points to evidence strength, and 3 points to creator potential. It does not add a seventh score factor and it does not replace the weighted six-factor score.

### Novelty

Novelty starts from the AI analyst or fallback topic novelty estimate, converted from 0-1 into 0-100. It is then adjusted down when history shows the topic is recurring:

```
recurrence penalty = min(24, (appearanceCount - 1) * 4)
cooling penalty = 4 when historical score slope < -4
```

So a topic can still be valuable while losing novelty if it has appeared often in prior snapshots.

### Evidence Strength

Evidence strength asks whether the topic is supported by relevant, reliable evidence rather than a single noisy artifact:

```
evidence relevance * 45%
+ evidence volume * 20%
+ source reliability * 20%
+ source role reliability * 15%
```

Evidence relevance is source-normalized before scoring. Hacker News relevance uses 70% log-scaled points and 30% log-scaled comments, capped at 500 points and 200 comments. Apify-backed sources derive relevance from available metrics: no metrics starts at 0.45, and metric totals are log-scaled up to 5,000.

Source reliability combines source status and quality tier. Missing or unknown quality defaults to secondary for this calculation:

| Status   | Weight |
| -------- | ------ |
| active   | 1.00   |
| degraded | 0.65   |
| offline  | 0.25   |

| Quality Tier | Weight |
| ------------ | ------ |
| primary      | 1.00   |
| secondary    | 0.85   |
| community    | 0.70   |
| low          | 0.45   |

Source role reliability uses these weights:

| Role       | Weight |
| ---------- | ------ |
| research   | 1.00   |
| developer  | 0.95   |
| launch     | 0.90   |
| creator    | 0.85   |
| news       | 0.75   |
| discussion | 0.70   |

Low-quality evidence can be displayed, but scoring caps each low-quality source to two items per topic so one low-quality source cannot dominate a score.

Source-local lift can add a small capped support value to evidence strength when the source-local baseline is available. Extreme lift is treated as verify-first context; it is not automatically better than moderate repeatable lift.

### Source Diversity

Source diversity rewards both distinct sources and distinct source roles:

```
min(source_count / 4, 1) * 75
+ min(role_count / 3, 1) * 25
```

A topic with four sources and three roles reaches the diversity cap.

Consensus ratio is published separately from the weighted diversity factor. It counts healthy, non-offline sources that confirm the topic and divides by the number of healthy sources in the current run. When there are no healthy sources or no linked evidence, the value is unavailable instead of zero.

Role shares are also published separately. They count linked evidence by source role and normalize to shares. The builder signal is the developer plus research role share. It is used by lifecycle classification and Workbench filtering; it does not replace the source diversity factor.

Camp classification is another derived display signal over the same role shares. Trend Finder maps roles to camps as follows:

| Camp       | Source Roles                            |
| ---------- | --------------------------------------- |
| Early      | developer, research, launch, discussion |
| Mainstream | creator, news                           |
| Unknown    | unknown                                 |

`topic.camp` publishes an explicit state, dominant camp, early share, mainstream share, source-role evidence counts, unknown-role count, and a bounded derivation note. Mainstream share is damped before classification:

```
damped_mainstream = mainstream_evidence_count * 0.18
mainstreamShare = damped_mainstream / (early_evidence_count + damped_mainstream)
```

This keeps creator/news firehoses from making a builder-led topic look crowded too early. `mainstreamShare <= 0.45` classifies as `early`, `mainstreamShare >= 0.68` classifies as `mainstream`, and values between those thresholds classify as `balanced`. When a topic has no early or mainstream role evidence, camp state is `unavailable`; Trend Finder does not infer a camp from unknown-role rows.

Camp classification is shown in Radar, Workbench filters, and MCP topic checks. It is a bounded derived display/classification signal. It is not a seventh weighted score factor and it does not replace the richer saturation formula.

### Attention Pattern

`topic.attentionPattern` labels what kind of attention is visible for a topic. It is additive, enum-only, and defaults to `unavailable` for legacy payloads. The supported values are:

| Value          | Meaning                                                               |
| -------------- | --------------------------------------------------------------------- |
| `adoption`     | Developer or research usage is the dominant source-role shape.        |
| `creator-hype` | Creator-role evidence plus reviewed engagement-farming title markers. |
| `announcement` | Launch-role evidence or release/announcement framing is dominant.     |
| `discourse`    | Discussion or news conversation is the dominant attention shape.      |
| `unavailable`  | Evidence, role shares, or title heuristics are insufficient.          |

The derivation starts from the same source-role shares used by source diversity, builder signal, and camp. Role-share precedence is deterministic, then bounded title heuristics are used only as a fallback. Creator-hype is intentionally narrow: it requires creator-role support and the reviewed Session 01 engagement-farming markers, so generic excitement does not become a hype label.

Attention pattern is not an action verdict. `actionRecommendation` still decides whether to act, monitor, review, or ignore. `attentionPattern` only describes the observed attention shape. It does not cap scores, demote action language, add a source, read comment bodies, or call an AI provider.

### Reception Signal

`topic.receptionSignal` labels aggregate-only reception for a topic. It is additive, enum-only, and defaults to `unavailable` for legacy payloads. The supported values are:

| Value         | Meaning                                                                            |
| ------------- | ---------------------------------------------------------------------------------- |
| `endorsed`    | Supported aggregate metrics show stronger public support than comment pressure.    |
| `contested`   | Aggregate comments indicate visible dispute or review pressure.                    |
| `ratioed`     | Aggregate comments outweigh support enough to block Act now wording.               |
| `mixed`       | Supported aggregate rows disagree, such as endorsed and contested rows together.   |
| `unavailable` | No defensible aggregate reception metric is available or the metric basis is thin. |

Reception derivation only reads normalized aggregate metric counts already in the payload, such as `points`, `upvotes`, and `comments`, plus source identity and source role. It does not read, cache, summarize, classify, or publish comment bodies, replies, transcripts, prompts, provider responses, private paths, or raw source rows. Unsupported source shapes and thin aggregate inputs return `unavailable`.

The derivation currently accepts aggregate comment-to-support evidence for reviewed discussion and launch-like sources, including Hacker News, Reddit, and Product Hunt style rows when those normalized metrics exist. The helper uses a minimum aggregate engagement floor before emitting a non-`unavailable` state. High comment pressure relative to support can produce `contested` or `ratioed`; strong support with low comment pressure can produce `endorsed`; conflicting supported rows produce `mixed`.

Reception does not change the core opportunity score. If a topic is `contested` or `ratioed`, source-breakdown derivation merges the `contested-reception` risk flag before action recommendations run. Action priority then applies a `contested_reception` cap and warning so those topics cannot become `act_now`; they remain eligible for `monitor`, `review`, or `ignore` depending on the rest of the evidence.

### Run Mood Aggregate

Trend Finder also projects a run-level mood tile from values already present in the generated payload. The aggregate is display context for the current run, not a topic score, prediction, or source pull. It combines:

* movement contribution from score deltas when a previous score exists, falling back to the topic movement status
* action verdict mix from Act now, Monitor, Review, and Ignore rows
* average topic saturation across ranked topics

The output is a bounded 0-100 mood label (`Quiet`, `Guarded`, `Warming`, `Active`, or `Heated`) plus input counts and top riser/top cooler callouts. The Brief pairs the read with prediction calibration (`hitRate` and `brierScore`) so the mood never stands in for proven forecast quality.

When a posting-window read is shown, it is deliberately banded: `Wide`, `Closing`, `Closed`, or `Unavailable`. The band is derived from top actionable topics using saturation and camp mainstream share. It never emits an integer day count or "days to mainstream" forecast.

### Risk Flags

Risk flags are deterministic caution chips on `topic.riskFlags`. They do not create a new score factor and they are not action verdicts. The current shipped flag set is:

| Flag                           | Meaning                                                                               |
| ------------------------------ | ------------------------------------------------------------------------------------- |
| `single-source-signal`         | The topic is supported by one source in the current scoring sample.                   |
| `originator-only`              | Reviewed identity evidence is dominated by one originating entity.                    |
| `low-quality-source-dominated` | Most scoring evidence comes from low-quality source tiers.                            |
| `research-only`                | Research evidence is present without developer, discussion, or launch adoption proof. |
| `stale-evidence`               | All dated evidence is older than the freshness threshold.                             |
| `placement-adjacent`           | Source-local placement signals indicate promoted or excluded placement.               |
| `generic-or-vague-topic`       | The topic label is generic, vague, or suppressed by the quality gate.                 |
| `high-noise-topic`             | Deterministic noise risk is high or the quality gate is suppressed.                   |
| `contested-reception`          | Aggregate reception is contested or ratioed and cannot support Act now wording.       |

`research-only` is derived from aggregate role composition during scoring. It requires research-role evidence, no developer/discussion/launch role evidence, and a dominant research share in the scored sample. Creator, news, or unknown rows do not provide adoption proof for this flag. The chip is a caution input for later operator review and action consistency checks; by itself it does not say to act, avoid, or promote a topic.

### Corroboration Gate

`topic.corroboration` is an additive derived object that separates source count from independent-origin confirmation. It defaults to an explicit `unavailable` state for legacy payloads and publishes only bounded display fields: `status`, `dominanceState`, independent entity count, source role count, evidence count, dominance ratio, caution, label, and explanation. It does not publish raw entity IDs, signal identity group IDs, private paths, prompts, provider responses, or raw source rows.

The derivation reuses reviewed metadata already in the run: source-local entity identity, competitor matches, and signal-identity syndication groups. Source ID fallback is used only as a last internal fallback and does not turn missing identity metadata into confirmed corroboration. A topic can therefore have `single-source-signal`, `originator-only`, both, or neither: the first is about source scarcity, while the second is about independent-origin scarcity.

| Status            | Meaning                                                                           |
| ----------------- | --------------------------------------------------------------------------------- |
| `unavailable`     | No reviewed identity basis exists, so no origin claim is made.                    |
| `originator-only` | Reviewed identity evidence is single-origin or dominated by one origin.           |
| `weak`            | Some independent-origin evidence exists, but role/entity spread is still limited. |
| `confirmed`       | Multiple independent origins and source roles support the topic.                  |

`originator-only` adds the `originator-only` risk flag, applies a bounded `corroboration_gate` score adjustment, and feeds action priority. Confirmed and unavailable corroboration do not receive the originator-only score downrank.

### Niche Fit

Niche fit comes from the AI analyst when AI analysis succeeds. The analyst sees the active Creator Lens audience, content format, topic focus, goal, and risk level. The value is then converted from 0-1 into 0-100.

When the AI runtime is unavailable, deterministic fallback estimates niche fit from text matches against Creator Lens `topicFocus` plus a risk-level bonus:

| Risk Level   | Fallback Bonus |
| ------------ | -------------- |
| safe         | 0.04           |
| balanced     | 0.10           |
| experimental | 0.16           |

### Creator Potential

Creator potential also comes from the AI analyst when AI analysis succeeds. It estimates whether the topic can become useful creator output: tutorials, workflows, newsletters, product ideas, demos, experiments, or audience questions.

Fallback creator potential combines niche fit, evidence relevance/engagement, and whether a content format is present in the Creator Lens.

Source-local actionability uses these display bands and actionability levels:

| Band           | Ratio Range | Actionability | UI Meaning                         |
| -------------- | ----------- | ------------- | ---------------------------------- |
| unavailable    | N/A         | unavailable   | Baseline cannot be calculated.     |
| below-baseline | < 0.9x      | low-signal    | Evidence trails its local context. |
| near-baseline  | 0.9x-1.5x   | watch         | Worth watching, not an outlier.    |
| moderate-lift  | 1.5x-3x     | repeatable    | Repeatable lift candidate.         |
| strong-lift    | 3x-8x       | repeatable    | Strong lift, still capped.         |
| extreme-lift   | >= 8x       | verify-first  | Verify-first one-off risk.         |

Actionability is guidance for inspection. It is not a promise that a topic is easy to replicate, and it is not a ranking override. A moderate repeatable lift can be more useful than an extreme one-off, especially when source diversity, evidence strength, or Creator Lens fit is weak.

The cross-source outlier preset is a Workbench presentation over this same source-local lift model. It sorts evidence by reviewed source-local ratios and actionability labels across all supported sources. It is not a separate score factor and it does not use Alpha Radar's single-channel baseline shortcut.

## Derived Topic Signals

### Signal Aging

`signalAging` is a bounded display signal derived from scoring evidence. It publishes:

* status: `fresh`, `active`, `cooling`, `stale`, or `unavailable`
* freshness score, latest age, median age, and fresh/active/cooling/stale evidence counts
* decay penalty, freshness boost, recent confirmation score, and old-source pressure
* up to six source-role contributions with role, evidence count, half-life, age summary, freshness, contribution score, status, and old-source pressure
* unavailable reason and warning codes

Unavailable states are explicit: invalid input, invalid generated time, no evidence, invalid evidence dates, or insufficient history. Trend Finder does not infer freshness from missing dates or too little usable evidence.

Signal aging is separate from the lifecycle stage. The payload does not add Trends-Finderz lifecycle labels such as Emerging, Stale, or Dormant, and it does not replace the Trend Finder lifecycle taxonomy. It participates in final ranking only through the bounded lifecycle multiplier described above.

### Saturation

Saturation estimates how crowded a topic already is. It combines:

```
source pressure * 24%
+ current volume pressure * 28%
+ recurrence pressure * 16%
+ source diffusion pressure * 16%
+ mention density pressure * 10%
+ mainstream-term pressure * 10%
- single-source/developer dominance discount
```

Source pressure compares distinct source count with healthy source coverage. Current volume pressure compares current evidence volume with historical peak when history exists, or with the evidence-volume score for new topics. Recurrence pressure rises with historical appearance count. Source diffusion looks at how spread out scoring evidence is across sources and source roles. Mention density is log-scaled from scoring evidence count. Mainstream-term pressure is a bounded match against reviewed broad AI terms in the topic text. Single-source and developer-dominant topics receive a bounded discount so one builder channel does not look like broad market saturation. A topic with no evidence or no healthy source denominator gets an unavailable saturation value.

Saturation is a display and classification signal. It supports radar axes, chips, Workbench filters, lifecycle classification, and hidden-gem scoring. It does not directly add or subtract points from the weighted six-factor score.

### Hidden-Gem Score

The boolean hidden-gem marker still uses the strict thresholds below. The continuous `hiddenGemScore` ranks hidden-gem candidates among themselves and helps the Workbench sort early opportunities.

The continuous score combines:

```
overall score * 18%
+ novelty margin * 24%
+ evidence-strength margin * 18%
+ inverse saturation * 24%
+ low-volume fit * 16%
+ strict hidden-gem bonus
```

Unavailable saturation uses a neutral inverse-saturation value, not a guessed crowding estimate.

### Topic Quality And Visibility

Topic quality is a deterministic gate derived from existing topic, scoring, source, and evidence fields. It does not call new sources, add dependencies, or publish raw source payloads. The helper writes these bounded fields per topic:

| Field                        | Meaning                                                                                                                    |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `topicQualityScore`          | 0-100 quality score from specificity, source trust, confirmation, signal quality, actionability, freshness, and penalties. |
| `topicQualityClarity`        | `clear`, `needs_review`, or `vague` topic-label clarity.                                                                   |
| `topicNoiseRisk`             | `low`, `medium`, or `high` deterministic noise risk.                                                                       |
| `topicQualityGate`           | `pass`, `watch`, or `suppress` quality-gate status.                                                                        |
| `topicNoiseDownrank`         | Bounded score downrank applied to the default ranked sort.                                                                 |
| `topicVisibilityBand`        | Display band: `priority`, `strong`, `watch`, `research_only`, `suppressed`, or `rejected`.                                 |
| `topicVisibilityReasonCodes` | Bounded machine-readable reasons for the visibility decision.                                                              |
| `isEarlyHiddenGemRescued`    | Whether the hidden-gem rescue kept an early low-saturation signal visible.                                                 |

The quality score penalizes broad generic labels, filler/listicle wording, tutorial or boilerplate patterns, weak source confirmation, saturation pressure, and cooling evidence. Strong cross-source confirmation can keep a topic in `pass`, but high-noise or suppressed topics are downranked.

Fallback-mode topics use the same helper. Generic or high-noise fallback rows are capped lower after downranking so source-ID clusters do not rank beside specific evidence-backed opportunities.

Visibility is display-only. Topics are not removed from payloads. The Trends view hides `suppressed` and `rejected` rows by default behind a suppressed-noise summary and show control, while Workbench filters can still inspect by visibility band or noise risk.

Early hidden-gem rescue keeps a strict hidden-gem candidate visible when it has a high continuous hidden-gem score, usable quality, low saturation, non-stale evidence, and is not a generic/high-noise topic.

### Action Verdicts And Consistency QA

Each topic also publishes an additive `actionRecommendation` object and an additive `actionConsistency` QA object. These fields do not change the six factor score and do not create an Action Queue grouping. Ranked trends, Hidden Gems, Brief topics, and selected-topic projections consume the same per-topic fields.

Action verdicts use the existing topic fields only:

| Verdict   | Meaning                                                                                             |
| --------- | --------------------------------------------------------------------------------------------------- |
| `act_now` | Fresh, reliable, visible evidence supports timely creator or product action.                        |
| `monitor` | The signal is useful, but evidence, visibility, quality, or timing keeps it below `act_now`.        |
| `review`  | The topic needs evidence, quality, research-only, or wording review before action language is safe. |
| `ignore`  | The topic is too weak, stale, noisy, suppressed, rejected, or crowded to prioritize in this run.    |

The action score is deterministic and bounded to 0-100. It combines final score, creator potential, evidence strength, momentum, niche fit, novelty, topic quality, visibility, hidden-gem score, source diversity, evidence volume, signal aging, lifecycle, movement, saturation fit, sample confidence, and topic confidence. It then applies hard caps:

| Cap                                  | Effect                                                                   |
| ------------------------------------ | ------------------------------------------------------------------------ |
| Research-only                        | Caps action score and keeps the visible verdict at `review` or below.    |
| Visibility watch/suppressed/rejected | Prevents weak visibility from becoming an urgent action.                 |
| Weak evidence                        | Requires at least two sources and three evidence mentions for `act_now`. |
| Stale or cooling evidence            | Demotes stale action language and keeps cooling topics below `act_now`.  |
| Quality/noise                        | Suppressed quality or high noise blocks action wording.                  |
| Saturation                           | High saturation restrains action language for crowded topics.            |
| Lifecycle saturation                 | Saturated lifecycle prevents urgent early-opportunity framing.           |
| Contested reception                  | Ratioed or contested aggregate reception stays below `act_now`.          |
| Originator-only corroboration        | Single-origin evidence stays below `act_now` pending independent proof.  |

`act_now` requires all of these: reliable evidence, `priority` or `strong` visibility, pass quality gate, low noise, fresh or active signal aging, no research-only cap, no stale/cooling cap, no high-saturation cap, and no saturated lifecycle or contested-reception cap.

Action reason and warning arrays are bounded machine-readable codes. Public UI copy is derived from those codes and from bounded summary fields. The collector does not use new source calls, AI rewrite calls, private paths, raw snippets, or unbounded generated text for action verdict derivation.

Consistency QA checks the visible action against:

* visibility band
* signal aging
* research-only status
* source and evidence coverage
* quality gate and noise risk
* saturation pressure
* creator-angle, `whyNow`, and hook overstatement language

The QA status is `clean`, `review`, or `blocked`. Review status adds caution metadata for the UI. Blocked status can demote the visible verdict to `review` or `ignore`. Demotion changes only the action verdict, label, summary, and next step. It preserves the original `creatorAngle`, `whyNow`, and `suggestedHooks` so the UI can show a caution chip beside the original angle pack instead of rewriting generated copy.

Collector trace additions for action verdicts are sanitized. They include verdict counts, QA status counts, warning counts, caution counts, demotion counts, bounded reason/warning/cap codes, scores, and enum statuses. They do not include raw creator text, raw evidence snippets, source URLs, or private filesystem paths.

Collector trace additions for reception are also enum-only. The trace records a reception signal count summary and each topic's `receptionSignal` enum. It does not include aggregate metric ratios, comment counts, comment bodies, snippets, titles, or raw source payloads as reception explanations.

### Risk Flags

Risk flags are deterministic labels derived from bounded topic evidence:

| Flag                           | Trigger                                                                                   |
| ------------------------------ | ----------------------------------------------------------------------------------------- |
| `single-source-signal`         | The topic has evidence, but only one distinct source is supporting it.                    |
| `originator-only`              | Reviewed identity evidence is single-origin or dominated by one origin.                   |
| `low-quality-source-dominated` | More than half of linked evidence comes from low-quality-tier sources.                    |
| `research-only`                | Research evidence is present without developer, discussion, or launch adoption proof.     |
| `stale-evidence`               | Every linked evidence timestamp is at least 30 days older than the generated run time.    |
| `placement-adjacent`           | At least half of linked evidence is placement-excluded or placement-adjacent for signals. |
| `generic-or-vague-topic`       | Topic quality marks the label generic, vague, or suppressed by the quality gate.          |
| `high-noise-topic`             | Topic quality marks the topic high-noise or suppressed by the quality gate.               |
| `contested-reception`          | Aggregate reception is contested or ratioed and cannot support Act now wording.           |

Malformed risk input fails closed in the collector and records a warning instead of publishing invented flags.

### No-Invented-Metrics Boundary

Trend Finder does not ship Alpha Radar `tbts`, `peak_estimate_days`, or time-to-breakout point estimates. It also does not ship reciprocal-rank-fusion as a scoring input. Those ideas remain unimplemented mapping context because the current score must stay grounded in observed evidence, bounded history, reviewed source metadata, and explicit unavailable states.

## Hidden Gem Criteria

A topic is marked as a hidden gem only when all of these are true:

| Criterion         | Required Value |
| ----------------- | -------------- |
| Overall score     | >= 55          |
| Novelty factor    | >= 70          |
| Evidence strength | >= 35          |
| Source count      | <= 2           |
| Evidence count    | <= 5           |

This means "hidden gem" does not mean "weak." It means the topic has enough score and evidence to inspect, but still has limited source saturation.

Hidden Gems surfaces now sort by continuous hidden-gem score first, then score, novelty, and deterministic tie-breakers. The strict boolean still decides which topics qualify for Hidden Gems and watchlist reasons.

## Watchlist Criteria

The watchlist keeps at most eight generated rows per run. A topic qualifies if it matches at least one reason:

| Reason Code                 | Exact Rule                                                                             |
| --------------------------- | -------------------------------------------------------------------------------------- |
| `analyst-reason`            | The AI analyst or fallback topic has a non-empty `watchlistReason`.                    |
| `hidden-gem`                | The topic is a hidden gem.                                                             |
| `rising-delta`              | Current score is at least 10 points above the previous score.                          |
| `creator-fit`               | Score >= 55, niche fit >= 80, and creator potential >= 75.                             |
| `high-novelty-low-evidence` | Score >= 35, topic novelty >= 78%, and evidence strength <= 55 or evidence count <= 5. |

If multiple reasons match, the primary reason is chosen by priority:

```
analyst-reason > hidden-gem > rising-delta > creator-fit > high-novelty-low-evidence
```

Rows are then sorted by reason priority, score, score delta, name, and ID.

The `high-novelty-low-evidence` watchlist rule uses `topic.novelty` converted from its 0-1 analyst/fallback value when available. That is subtly different from hidden gem scoring, which uses the history-adjusted novelty score inside `scoreBreakdown.novelty`.

Generated Watchlist rows are recalculated from the current payload on each run. Browser-local pin baselines, notes, and tags can add operator context in the Watchlist UI, but they do not change generated watchlist qualification, topic scores, score factors, action verdicts, static Brief export, or source evidence.


---

# 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/scoring.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.