> 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/phase24-session08-cross-surface-documentation-reference-mode/spec.md).

# Session Specification

**Session ID**: `phase24-session08-cross-surface-documentation-reference-mode` **Phase**: 24 - Trend Finder Outlier Signal Upgrade **Status**: Not Started **Created**: 2026-06-08

***

## 1. Session Overview

This session aligns the Trend Finder documentation and in-app Reference mode after Phase 24 sessions 01 through 07 have landed. The feature sessions added source-local scoring signals, delta-aware enrichment, browser-safe evidence assets, local source setup, scheduler first-run controls, Signal Workbench triage, and static Brief export. Those behaviors now need one coherent operator-facing manual set.

The work is intentionally documentation-first with a small Reference mode test surface. The committed Markdown manuals remain the source of truth for Reference mode, and the in-app registry should continue to import the same documents without broken links or stale labels.

The session also protects the phase boundary. Manuals must document what is implemented, clearly label optional or deferred hosting/source expansion, and avoid implying public deployment, unreviewed sources, raw transcript exposure, or browser access to private caches and logs.

***

## 2. Objectives

1. Align the five Phase 24 Trend Finder manuals with the implemented sessions.
2. Keep the in-app Reference mode registry and Markdown imports synchronized.
3. Add focused tests that prove registered manuals remain importable and linked.
4. Preserve local-only, browser-safe, and implemented-vs-deferred boundaries.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase24-session01-source-local-scoring-signals` - source-local scoring, placement exclusions, and actionability labels exist.
* [x] `phase24-session02-delta-aware-enrichment-spend-accounting` - enrichment cache, pruning, and spend summaries exist.
* [x] `phase24-session03-browser-safe-evidence-assets-file-hardening` - asset manifest, bridge, and file-safety rules exist.
* [x] `phase24-session04-source-setup-target-configuration` - local Source Setup bridge and target constraints exist.
* [x] `phase24-session05-scheduler-first-run-live-progress-controls` - scheduler status, first-run panel, and live progress controls exist.
* [x] `phase24-session06-signal-workbench-local-triage` - Workbench and browser-local triage semantics exist.
* [x] `phase24-session07-static-brief-export` - static Brief export and privacy guards exist.

### Required Tools/Knowledge

* Bun 1.3.14 project toolchain.
* Vitest for focused Reference mode and Markdown import tests.
* Existing Trend Finder docs under `docs/extensions/`.
* Existing Reference mode code under `src/extensions/trend-finder/`.

### Environment Requirements

* Work from the repository root.
* Do not require live Apify, AI runtime, scheduler, or browser bridge secrets.
* Generated private runtime data under `.cache/` and `src/data/live-data.json` remains out of git.

***

## 4. Scope

### In Scope (MVP)

* Operators can read accurate scoring documentation for source-local baselines, promoted/pinned exclusions, bounded score lifts, and actionability banding.
* Operators can read accurate pipeline documentation for enrichment cache, retention/pruning, spend accounting, scheduler status, live progress, and static Brief export.
* Operators can read accurate source documentation for source setup, target fields, reviewed-source validation, source spend, and promoted/pinned handling.
* Operators can read accurate UI documentation for Source Setup, Signal Workbench, local triage, media assets, first-run controls, live progress, and static export.
* Operators can read accurate runtime/provenance documentation for Engine Replay labels covering enrichment skips, spend, pruned assets, dropped promoted/pinned rows, asset failures, scheduler status, and live progress.
* Reference mode continues to expose the updated manuals through stable IDs, labels, descriptions, and Markdown imports.
* Tests prove registered Reference mode Markdown files remain importable and linkable.

### Out of Scope (Deferred)

* New Trend Finder feature behavior - Reason: this session is documentation and reference alignment.
* Public static hosting automation - Reason: static Brief export hosting remains opt-in operator work.
* New public source adapters or media permissions - Reason: each source still requires separate compliance review.
* Changing durable project conventions - Reason: no new repo-wide rule is expected from a docs alignment pass.
* Updating generated private runtime data - Reason: manuals should not depend on local private artifacts.

***

## 5. Technical Approach

### Architecture

The session treats committed Markdown manuals as the canonical reference contract. `src/extensions/trend-finder/reference-docs.ts` imports those manuals as raw text and supplies stable IDs, labels, descriptions, and source paths to Engine Replay Reference mode. Tests should verify that registry metadata, source paths, Markdown headings, and internal Trend Finder doc links remain coherent.

Documentation changes should be cross-surface rather than speculative. Each manual should describe the implemented behavior from sessions 01 through 07 and call out optional/deferred behavior where it matters: public hosting, unreviewed sources, raw transcripts, private caches, raw logs, billing payloads, credentials, local triage notes, and scheduler internals.

### Design Patterns

* Static registry: Reference mode continues to use compile-time Markdown imports.
* Documentation-as-contract: manuals describe the browser-safe payload and private runtime boundary, not raw implementation internals.
* Focused tests: use Vitest to prove registry and Markdown behavior without needing live source collection.
* Additive updates: prefer precise section edits over broad rewrites.

### Technology Stack

* TypeScript 6.0.3.
* React 19 and Vite raw Markdown imports.
* Vitest 4.1.6.
* Bun 1.3.14.

***

## 6. Deliverables

### Files to Create

| File          | Purpose                                       | Est. Lines |
| ------------- | --------------------------------------------- | ---------- |
| None expected | This session updates existing docs and tests. | N/A        |

### Files to Modify

| File                                                                                   | Changes                                                                                             | Est. Lines |
| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | ---------- |
| `docs/extensions/README_docs-extensions.md`                                            | Align Reference mode and static export overview.                                                    | \~30       |
| `docs/extensions/trend-finder-scoring.md`                                              | Align scoring, source-local lift, placement exclusion, and actionability guidance.                  | \~50       |
| `docs/extensions/trend-finder-pipeline.md`                                             | Align enrichment, spend, scheduler, live progress, asset, and static export contract.               | \~50       |
| `docs/extensions/trend-finder-sources.md`                                              | Align reviewed source setup, target fields, source spend, cache state, and placement handling.      | \~45       |
| `docs/extensions/trend-finder-ui-surfaces.md`                                          | Align Workbench, Source Setup, assets, scheduler, live progress, Brief, and static export surfaces. | \~55       |
| `docs/extensions/trend-finder-runtime-and-provenance.md`                               | Align Engine Replay labels, runtime provenance, progress, spend, assets, and Reference mode.        | \~55       |
| `src/extensions/trend-finder/reference-docs.ts`                                        | Update registry labels/descriptions/source paths only if needed.                                    | \~15       |
| `src/extensions/trend-finder/__tests__/reference-docs.test.ts`                         | Expand import, path, and link assertions for updated manuals.                                       | \~60       |
| `src/extensions/trend-finder/components/__tests__/trend-reference-doc-viewer.test.tsx` | Expand viewer/link assertions if Reference mode behavior changes.                                   | \~35       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Updated manuals accurately describe implemented Phase 24 behavior.
* [ ] Optional/deferred behavior is labeled clearly and not presented as a default product path.
* [ ] Reference mode registry imports every expected manual with stable IDs, source paths, labels, descriptions, and non-empty Markdown.
* [ ] Cross-document Trend Finder links resolve to Reference mode targets.
* [ ] User-facing manuals avoid example-specific Instagram/Reels product language except when saying what was not copied.

### Testing Requirements

* [ ] Focused Reference mode tests pass.
* [ ] Markdown viewer/link tests pass if touched.
* [ ] Relevant format, lint, and type checks pass or any skipped command is documented with reason.

### Non-Functional Requirements

* [ ] Browser-visible documentation reinforces reviewed-source, local-only, and private-cache boundaries.
* [ ] No manual implies unreviewed sources, raw transcript exposure, raw logs, raw Actor/Dataset rows, billing payloads, account auth, or default public deployment.
* [ ] Docs remain concise enough to be useful in in-app Reference mode.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code and docs follow project conventions.

***

## 8. Implementation Notes

### Key Considerations

* The manuals already contain Phase 24 sections. Implementation should audit, tighten, and fill gaps rather than rewrite the documentation from scratch.
* `docs/extensions/trend-finder-*.md` files are imported directly by Reference mode, so headings and local links should stay stable when possible.
* The Phase 24 PRD says docs must preserve implemented-vs-deferred labeling and avoid example-specific source language in user-facing manuals.

### Potential Challenges

* Cross-doc drift: Update the shared terms in all affected manuals and add tests for registry/source-path coverage.
* Over-documenting planned behavior: Tie each claim back to sessions 01 through 07 and label optional hosting or future source expansion explicitly.
* Broken in-app anchors: Prefer stable headings and test representative Reference mode link resolution.

### Relevant Considerations

* \[P00] **Do not document planned features as implemented**: The manuals must distinguish shipped local features from optional hosting and future source expansion.
* \[P02] **New source adapters need per-source compliance review**: Source docs must keep unreviewed source expansion out of the implemented path.
* \[P02] **Static extension registry requires code changes**: Reference mode remains a compile-time registry, not dynamic docs loading.
* \[P11] **Scheduler state/log privacy boundary**: Scheduler docs may expose only safe labels, statuses, durations, warning counts, freshness, and command hints.
* \[P05] **Script-only runtime boundary**: Auth, provider responses, raw source payloads, and private cache details stay out of browser manuals and payloads.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Reference mode registry drift breaks in-app manual imports.
* Cross-document links resolve to stale or missing Reference mode targets.
* Documentation presents optional/deferred behavior as implemented or default.

***

## 9. Testing Strategy

### Unit Tests

* Expand `reference-docs.test.ts` to assert registry order, source paths, non-empty Markdown, core Phase 24 section presence, and link resolution.
* Expand the viewer test only if Reference mode rendering or link behavior is changed.

### Integration Tests

* Run focused Vitest files that cover Reference mode imports and Markdown viewer behavior.

### Manual Testing

* Inspect the updated manuals in source form for implemented-vs-deferred language and private-boundary wording.
* If a dev server is already running during implementation, spot-check Engine Replay Reference mode. Do not require a server only for this docs session.

### Edge Cases

* Empty imported Markdown should fail tests.
* Renamed manuals must update both registry source paths and filename resolver.
* Local links to Trend Finder manuals should resolve to Reference mode tabs.
* Non-Reference docs links should remain code/document references, not broken in-app tab switches.

***

## 10. Dependencies

### External Libraries

* None new.

### Other Sessions

* **Depends on**: sessions 01 through 07 in Phase 24.
* **Depended by**: `phase24-session09-end-to-end-validation-release-hardening`.

***

## 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/phase24-session08-cross-surface-documentation-reference-mode/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.