> 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/sessions/phase28-session13-keyword-packs-rotation-and-coverage/spec.md).

# Session Specification

**Session ID**: `phase28-session13-keyword-packs-rotation-and-coverage` **Phase**: 28 - Trend Finder Trends-Finderz Adoption **Status**: Not Started **Created**: 2026-06-14

***

## 1. Session Overview

This session adds the first reviewed keyword-pack layer to Trend Finder collection. Today, reviewed Apify sources use small static search targets in their declarations or private source setup file. The session introduces a committed category x keyword vocabulary, a default `balanced` scan mode, an opt-in `focused` category mode, and per-source term compilation that continues to respect the existing source caps, quality tiers, and spend labels.

The work is compliance-gated because it changes Actor inputs and source query shape. The implementation must record the source-compliance review before changing collector behavior, keep user free-text out of the committed keyword path, and preserve the Source Setup allowlist model instead of adding a raw Actor input editor.

The session also records the selected stable-core plus rotating-tail keyword window in sanitized run evidence. That trace lets movement and source-health layers distinguish "not scanned this run" from "cooling," and gives operators a bounded coverage summary in Source Setup without exposing raw Actor inputs, Dataset metadata, private paths, or credentials.

***

## 2. Objectives

1. Complete and record the keyword-input compliance review before any Actor input change lands.
2. Add a pure keyword-pack compiler with reviewed categories, `balanced` and `focused` modes, stable-core keywords, deterministic seeded tail rotation, and per-source caps.
3. Wire keyword windows through source collection, engine trace, and movement context so rotated-out topics are treated as not scanned instead of cooling.
4. Surface bounded keyword coverage QA in Source Setup with schema defaults, view-model labels, component coverage, and focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase24-session04-source-setup-target-configuration` - Source Setup allowlist, local bridge, and reviewed target-field boundaries exist.
* [x] `phase28-session02-signal-quality-score-and-collection-health` - collection health and source coverage counters exist for extension.
* [x] `phase28-session03-calibration-version-and-confidence-dampener` - scoring-version context protects movement comparisons across collection changes.
* [x] `phase28-session12-brief-qa-markdown-export-and-kpi-strip` - current Trend Finder UI, docs, and validation surfaces are complete before Tier 4 collection work begins.

### Required Tools/Knowledge

* Bun 1.3.14, TypeScript, Vitest, React 19, Tailwind CSS 4, Zod, and the existing Trend Finder source setup and collector patterns.
* Current source declarations in `scripts/extensions/trend-finder/sources/apify-source-config.ts`.
* Existing source setup state in `scripts/extensions/trend-finder/sources/source-setup.ts` and `src/extensions/trend-finder/components/source-setup-panel.tsx`.
* Movement analyst and scoring-version context in `scripts/lib/ai-runtime/movement-analyst.ts` and `scripts/lib/ai-runtime/scoring.ts`.
* Trends-Finderz keyword references under `EXAMPLES/trends-finderz/lib/config/` and `EXAMPLES/trends-finderz/lib/scan/keyword-coverage.ts`.

### Environment Requirements

* No live Apify credential is required for implementation or tests.
* Any source input widening must be documented before collector code changes.
* Runtime scan mode should be script-side only, using safe env or scheduler configuration such as `FINDTREND_KEYWORD_SCAN_MODE` and `FINDTREND_KEYWORD_SCAN_CATEGORY`.

***

## 4. Scope

### In Scope (MVP)

* Trend Finder maintainers can review and audit the keyword-input compliance stance before Actor inputs are changed.
* Trend Finder collection has a committed category keyword pack with normalized reviewed terms, no user free-text, deterministic ordering, and bounded output.
* The default scan mode is `balanced`, selecting a stable core plus a rotated tail across all reviewed categories.
* The opt-in `focused` mode accepts one reviewed category and keeps the same stable-core plus deterministic tail behavior for that category.
* Per-source compilation maps keyword windows only into reviewed query fields such as `query`, `q`, `searchTerms`, `searchQueries`, or `searchQuery`, and respects source-specific caps, item caps, charge ceilings, and spend labels.
* Engine trace records mode, category, selected counts, coverage counts, and per-source cap usage without raw Actor input or private runtime data.
* Movement analysis receives enough scan-window context to avoid presenting rotated-out prior topics as normal cooling.
* Source Setup shows a bounded keyword coverage QA summary with ready, review, and thin coverage states.
* Tests cover pack compilation, cap enforcement, seeded rotation determinism, coverage statuses, collector wiring, trace sanitization, UI projection, and movement "not scanned" behavior.

### Out of Scope (Deferred)

* New direct first-party adapters - *Reason: Session 14 owns direct arXiv, GitHub, RSS, and HN paths.*
* Raising source item caps or spend ceilings - *Reason: this session must stay cost-neutral.*
* User-authored free-text keyword packs - *Reason: reviewed committed config is the compliance boundary.*
* Deep scan mode - *Reason: the session stub only approves `balanced` default and `focused <category>` opt-in for MVP.*
* Browser controls that mutate scan mode - *Reason: mode selection belongs to script-side env or scheduler config until a separate reviewed settings path exists.*

***

## 5. Technical Approach

### Architecture

Create `scripts/extensions/trend-finder/sources/keyword-packs.ts` as the pure source of truth for category names, reviewed keywords, mode parsing, seeded rotation, per-source caps, compilation, and coverage QA. The module should return plain typed objects that the collector and tests can consume without performing network calls or reading private source files.

The collector resolves the scan mode once per run from script-side env or scheduler config, passes the resolved window into Apify source preparation, and records only sanitized counts and labels in trace data. Source input mutation should happen on cloned source config objects immediately before collection so the reviewed static declarations remain declarations, not hidden runtime defaults.

Browser code receives only bounded schema fields: selected mode/category, category coverage rows, source cap summaries, and warnings. Source Setup projects those fields into compact QA labels. Movement analysis receives script-side scan eligibility context so fallback and AI-backed records can avoid misclassifying unscanned prior topics as cooling.

### Design Patterns

* Compliance before collection: source docs and onboarding notes must be updated before Actor-input behavior changes.
* Pure helper first: implement keyword normalization, rotation, cap math, and coverage QA in isolated functions before collector wiring.
* Project before rendering: UI displays bounded coverage summaries parsed by schema defaults, never raw Actor inputs.
* Deterministic rotation: `generatedAt` date controls tail windows so tests and engine traces can reproduce a run.
* Fail closed on unknown mode/category: invalid scan env falls back to `balanced` with a warning instead of widening collection.

### Technology Stack

* TypeScript 6, Bun 1.3.14, Vitest.
* Existing Trend Finder script collectors and source adapters.
* Existing Zod schema defaults for browser payload compatibility.
* Existing React 19, Tailwind CSS 4, and dense dashboard component patterns for Source Setup.

***

## 6. Deliverables

### Files to Create

| File                                                                                 | Purpose                                                                                                                                | Est. Lines |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `scripts/extensions/trend-finder/sources/keyword-packs.ts`                           | Reviewed categories, keyword packs, scan mode parsing, seeded rotation, per-source compilation, cap enforcement, and coverage summary. | \~420      |
| `scripts/extensions/trend-finder/sources/__tests__/keyword-packs.test.ts`            | Unit tests for category validation, normalization, dedupe, caps, rotation determinism, mode fallback, and coverage statuses.           | \~260      |
| `src/extensions/trend-finder/components/keyword-coverage-summary.tsx`                | Compact Source Setup coverage summary component with bounded rows and accessible labels.                                               | \~160      |
| `src/extensions/trend-finder/components/__tests__/keyword-coverage-summary.test.tsx` | Component tests for ready/review/thin states, empty data, focused mode labels, and long text handling.                                 | \~140      |

### Files to Modify

| File                                                                            | Changes                                                                                                                    | Est. Lines |
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | ---------- |
| `docs/sources/apify-source-onboarding.md`                                       | Record the Phase 28 keyword-pack review gate, affected reviewed query fields, and no-free-text rule.                       | \~90       |
| `docs/extensions/trend-finder-sources.md`                                       | Document scan modes, keyword rotation, source caps, coverage QA, and script-side env keys as shipped behavior.             | \~120      |
| `scripts/extensions/trend-finder/sources/types.ts`                              | Add keyword window, coverage, and source cap summary contracts used by source setup and collection.                        | \~90       |
| `scripts/extensions/trend-finder/sources/apify-source-config.ts`                | Add reviewed keyword target metadata and validation for sources that may receive compiled terms.                           | \~160      |
| `scripts/extensions/trend-finder/sources/apify-adapter.ts`                      | Apply compiled keyword windows to cloned source inputs before Actor calls and preserve spend labels/warnings.              | \~170      |
| `scripts/extensions/trend-finder/collector.ts`                                  | Resolve scan mode, pass keyword context through collection, attach setup/schema summaries, and feed movement scan context. | \~220      |
| `scripts/extensions/trend-finder/engine-trace.ts`                               | Sanitize and summarize keyword window data in trace records and artifact counts.                                           | \~120      |
| `scripts/lib/ai-runtime/movement-analyst.ts`                                    | Extend input and fallback movement logic with not-scanned context for rotated-out topics.                                  | \~150      |
| `scripts/lib/ai-runtime/__tests__/movement-analyst.test.ts`                     | Cover not-scanned context and fallback behavior that avoids normal cooling labels.                                         | \~120      |
| `src/extensions/trend-finder/schema.ts`                                         | Add additive defaults for keyword window and coverage QA browser payload fields.                                           | \~150      |
| `src/extensions/trend-finder/engine-trace.ts`                                   | Add frontend engine trace schema and defaults for keyword window summaries.                                                | \~100      |
| `src/extensions/trend-finder/view-model.ts`                                     | Project coverage statuses, focused-mode labels, source cap summaries, and setup diagnostics.                               | \~160      |
| `src/extensions/trend-finder/components/source-setup-panel.tsx`                 | Render keyword coverage QA inside Source Setup without adding browser mutation controls.                                   | \~120      |
| `src/extensions/trend-finder/components/__tests__/source-setup-panel.test.tsx`  | Cover coverage summary rendering, empty states, and setup reload behavior.                                                 | \~100      |
| `scripts/extensions/trend-finder/__tests__/collector.test.ts`                   | Cover scan mode env parsing, collector warnings, trace payload, and source setup summary propagation.                      | \~160      |
| `scripts/extensions/trend-finder/sources/__tests__/apify-adapter.test.ts`       | Cover input cloning, keyword field mapping, cap enforcement, and spend label preservation.                                 | \~160      |
| `scripts/extensions/trend-finder/sources/__tests__/apify-source-config.test.ts` | Cover keyword target metadata validation and rejected unreviewed fields.                                                   | \~120      |
| `scripts/extensions/trend-finder/__tests__/engine-trace.test.ts`                | Cover sanitized keyword window summaries and unsafe value rejection.                                                       | \~100      |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Keyword-input compliance review is recorded before any source input widening lands.
* [ ] Keyword packs compile to deterministic per-source term lists within reviewed source caps and existing charge ceilings.
* [ ] Invalid scan mode or category input falls back to `balanced` with an explicit warning and no expanded source query.
* [ ] Stable core terms always run, while tail terms rotate deterministically by `generatedAt` date.
* [ ] Engine trace records the selected mode, category, source caps, selected counts, and coverage counts without raw Actor input, Actor IDs, Dataset IDs, credentials, or private paths.
* [ ] Rotated-out prior topics are treated as not scanned in movement context, not normal cooling.
* [ ] Source Setup shows per-category coverage statuses and source cap summaries with bounded rows and accessible labels.

### Testing Requirements

* [ ] Unit tests cover keyword normalization, dedupe, scan mode parsing, focused-category validation, cap enforcement, stable-core selection, seeded rotation, and coverage statuses.
* [ ] Source adapter tests prove compiled terms are applied to cloned inputs, unknown fields are rejected, spend labels remain present, and errors map to explicit warnings.
* [ ] Collector and engine trace tests cover env fallback, trace sanitization, setup summary propagation, and unsafe value rejection.
* [ ] Movement tests cover "not scanned" handling for rotated-out topics.
* [ ] Component and view-model tests cover Source Setup coverage QA, empty states, focused mode labels, and reload/re-entry behavior.

### Non-Functional Requirements

* [ ] No new dependency, credential flow, direct API adapter, hosted storage, browser source mutation path, or raw source editor is introduced.
* [ ] Browser-visible data stays bounded and excludes raw prompts, provider responses, raw Actor input, Dataset metadata, private paths, credentials, and token-shaped strings.
* [ ] Existing source item caps, charge ceilings, quality tiers, compliance statuses, and spend-accounting labels remain intact.

### Quality Gates

* [ ] All files ASCII-encoded
* [ ] Unix LF line endings
* [ ] Code follows project conventions
* [ ] Focused tests and relevant type checks pass or unrelated pre-existing failures are documented in implementation notes

***

## 8. Implementation Notes

### Key Considerations

* Static declarations remain reviewed metadata. Runtime keyword compilation must clone configured source objects before applying per-run term windows.
* Reviewed source setup target fields are the only fields eligible for keyword compilation; unknown or unreviewed fields must be rejected with warnings.
* Keyword coverage rows are operational QA, not proof of external source coverage. They should describe what Trend Finder attempted to scan.
* Source Setup can display scan mode and coverage, but it must not become a browser write surface for scan mode in this session.

### Potential Challenges

* Source-specific input shapes vary: use declaration metadata and tests rather than ad hoc field-name checks in the adapter.
* Rotation can confuse movement: pass explicit scan-window context into movement analysis and test the no-current-evidence path.
* Keyword packs can grow payloads: cap category rows, selected examples, and trace summaries before they reach browser schema.
* Compliance docs may reveal a blocker: record the blocker and keep affected sources on their existing static inputs instead of silently widening them.

### Relevant Considerations

* \[P02] **New source adapters need compliance review**: This session changes source inputs, so the source review gate applies even though no new adapter is added.
* \[P06] **Apify actor outputs remain operator-dependent**: Keep blocked, degraded, and reviewed-source states explicit before collection.
* \[P02] **Extension payloads and labels stay bounded**: Coverage rows and trace summaries must be bounded and additive.
* \[P05] **Script-only runtime boundary**: Keyword compilation and scan mode resolution stay under script-side collection paths.
* \[P01] **Extract pure functions, then test, then wire**: Build and test keyword-pack math before collector and UI integration.
* \[P27] **Reference manuals track shipped behavior only**: Documentation in this session must describe implemented scan behavior, not planned direct adapters.

### Behavioral Quality Focus

Checklist active: Yes Top behavioral risks for this session:

* Invalid mode or category input could silently widen collection if not parsed fail-closed.
* Async collector paths could mutate shared source declarations if inputs are not cloned per run.
* Rotated-out topics could be misread as cooling without explicit scan context.

***

## 9. Testing Strategy

### Unit Tests

* Keyword-pack compilation, normalization, dedupe, cap enforcement, seeded rotation, source field mapping, coverage statuses, env fallback, and explicit warning generation.

### Integration Tests

* Collector scan mode resolution, Apify adapter input cloning, engine trace sanitization, source setup summary propagation, and movement not-scanned behavior.

### Manual Testing

* Run a fixture-backed Trend Finder aggregate with default balanced mode and a focused category mode, then inspect Source Setup and Engine Replay for safe coverage summaries and preserved spend labels.

### Edge Cases

* Unknown focused category, empty keyword pack, duplicate keywords with different casing, source cap of zero, source without reviewed keyword target, invalid env values, missing generatedAt, unsafe trace payload, and legacy payloads without keyword coverage fields.

***

## 10. Dependencies

### External Libraries

* None new.

### Other Sessions

* **Depends on**: `phase24-session04-source-setup-target-configuration`, `phase28-session02-signal-quality-score-and-collection-health`, `phase28-session03-calibration-version-and-confidence-dampener`, `phase28-session12-brief-qa-markdown-export-and-kpi-strip`
* **Depended by**: `phase28-session14-direct-first-party-source-adapters`, `phase28-session15-documentation-validation-and-release`

***

## Next Steps

Run the implement workflow step to begin AI-led implementation.


---

# 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/sessions/phase28-session13-keyword-packs-rotation-and-coverage/spec.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.