> 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/.spec_system/archive/phases/phase_15/session_05_trend_finder_scheduler_job.md).

# Session 05: Trend Finder Scheduler Job

**Session ID**: `phase15-session05-trend-finder-scheduler-job` **Status**: Complete **Estimated Tasks**: \~15 **Estimated Duration**: 2-4 hours

***

## Objective

Add a dedicated scheduler job for Trend Finder refreshes with a lower default cadence than local agent aggregate.

Trend Finder should have an independent cadence and failure surface because it can call public sources, configured providers, Apify Actors, and optional AI runtime providers.

***

## Scope

### In Scope (MVP)

* Add a Trend Finder-only aggregate helper
* Preserve extension enablement through current extension config/env gates
* Preserve host/local live-data branches through merge writer
* Add scheduler registry entry, handler, package scripts, and status copy
* Surface safe provider/source readiness warnings and generated-data freshness
* Update Trend Finder and aggregate docs
* Tests for missing enablement, missing provider/source config, successful collector merge, warning-only runs, and timeout behavior
* Validation that Dream can consume recent agent aggregate output without forcing a Trend Finder refresh

### Out of Scope

* New public source adapters
* Source planner AI behavior
* Timer installation

***

## Detailed Tasks

1. Add a Trend Finder-only aggregate helper that runs just the Trend Finder collector path.
2. Ensure extension enablement still requires existing extension config/env.
3. Preserve host/local live-data branches through the merge writer.
4. Add `trend-finder` to the scheduler registry. If existing naming constraints require `trend-finder-refresh`, document the final reviewed job ID in the phase record before proceeding.
5. Define reviewed cadence candidates, likely daily and manual-oriented guidance.
6. Default Trend Finder scheduler cadence to daily.
7. Add an internal scheduler handler.
8. Add package scripts for `scheduler:trend-finder:run` and `scheduler:trend-finder:status`.
9. Add status copy for source/provider readiness, warnings, and generated-data freshness without exposing private source details.
10. Keep Apify tokens, provider auth paths, Actor inputs, prompts, and raw source payloads out of logs/status.
11. Update Trend Finder docs to explain scheduled refresh vs manual run control.
12. Update aggregate docs to explain why local agent refresh remains every 4 hours while Trend Finder defaults lower.
13. Add tests for missing extension enablement, missing provider/source config, successful collector merge, warning-only runs, and timeout behavior.
14. Validate that Dream can consume recent agent aggregate output without forcing a Trend Finder refresh.
15. Run focused scheduler, extension runner, and Trend Finder collector tests.

***

## Prerequisites

* [ ] Session 04 complete.
* [ ] Scoped write merge behavior is already validated.

***

## Deliverables

1. Trend Finder scheduler registry entry and handler.
2. Trend Finder scheduler package scripts and docs.
3. Tests proving only the extension branch is written.

***

## Handoff Gate

* [ ] Registry metadata, handler wiring, package scripts, status copy, and provider/source readiness warnings are complete.
* [ ] Tests prove Trend Finder refreshes only its owned extension branch.
* [ ] Trend Finder can be scheduled independently from local agent aggregate.

***

## Success Criteria

* [ ] Trend Finder can be scheduled independently of local agent aggregate.
* [ ] Trend Finder writes only its owned extension branch.
* [ ] Agent data remains fresh without running Trend Finder every time.


---

# 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/.spec_system/archive/phases/phase_15/session_05_trend_finder_scheduler_job.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.