> 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/runbooks/trend-finder-collector-logging.md).

# Trend Finder Collector Logging Runbook

Trend Finder scheduler runs write private diagnostics under the AI OS scheduler root. The default root is `~/.ai-os`; pass `--scheduler-root <path>` to status commands in tests or isolated local runs.

## Files

* Active run state: `scheduler/runs/trend-finder.active.json`
* Latest finished run state: `scheduler/runs/trend-finder.latest.json`
* Canonical run trace: `logs/scheduler/trend-finder-run-trace.v1.jsonl`
* Compact closeout summary: `logs/scheduler/trend-finder.latest-summary.json`
* Legacy scheduler log: `logs/scheduler/trend-finder.log`
* Private source-local artifact: `.cache/extensions/trend-finder/diagnostics/<run-id>/source-local.json`
* Private prediction Story Log artifact: `.cache/extensions/trend-finder/diagnostics/<run-id>/prediction-story-log.json`
* Private diagnostic manifest: `.cache/extensions/trend-finder/diagnostics/<run-id>/manifest.json`

The canonical trace and closeout summary are private. They are sanitized before write and must not contain raw prompts, provider responses, tokens, account data, private paths, raw source rows, or raw payload fragments.

Trend Finder also publishes a browser-safe `privateDiagnostics` manifest in `src/data/live-data.json`. That manifest contains only stable artifact IDs, redacted labels, statuses, counts, byte counts, and warning codes. It must not contain local paths, artifact file names, raw artifact rows, or diagnostic contents. Use the local files above for operator debugging.

## Commands

* Run once: `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder bun run scheduler:trend-finder:run`
* Human status: `bun run scheduler:trend-finder:status`
* JSON status: `bun run scheduler:trend-finder:status -- --json`
* JSONL trace stream during a run: `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder bun run scheduler:trend-finder:run -- --json`
* Verbose local diagnosis: `VITE_CLAUDE_OS_ENABLED_EXTENSIONS=trend-finder bun run scheduler:trend-finder:run -- --verbose`

## Warning Counts

`warningEventCount` counts total warning occurrences. `warningGroupCount` counts deduplicated warning groups. Legacy `warningCount` remains event-count compatible for older consumers.

Warning groups in the closeout summary include `code`, `source`, `count`, `firstSeenAt`, `lastSeenAt`, representative `message`, and a safe `reasonClass`.

## What To Inspect

* Active progress: use the status command and check active run ID, stage, elapsed time, lock owner, current source, completed source count, warnings so far, and last progress event.
* Payload growth: inspect `payloadBudget` in `trend-finder.latest-summary.json`; review total bytes, cap percentage, top branches, largest arrays, and whether the old 512 KB cap would have failed.
* Private diagnostics: inspect the manifest and scoped artifacts under `.cache/extensions/trend-finder/diagnostics/<run-id>/` when source-local derivation or prediction Story Log IDs/version details are needed. These files should parse as JSON and stay outside the browser payload except for the safe manifest.
* Source quality: inspect `sourceOutcomes` for source type, status, item count, evidence count, warning count, timeout budget, spend estimate, and fallback reason.
* Cache/retention issues: inspect warning groups with `cache` or `retention` codes and their `reasonClass`. Expected skipped or gated entries can remain warning-only; repeated permission, rename, malformed-entry, or delete-failed classes require operator action.
* Fallback quality: inspect `fallbackSummary`. Runtime auth, missing evidence, provider timeout/error, validation failure, and deterministic fallback gates reduce downstream quality and should be fixed before relying on analyst, movement, prediction, or retro output.


---

# 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/runbooks/trend-finder-collector-logging.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.