> 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-session07-static-brief-export/spec.md). # Session Specification **Session ID**: `phase24-session07-static-brief-export` **Phase**: 24 - Trend Finder Outlier Signal Upgrade **Status**: Not Started **Created**: 2026-06-08 *** ## 1. Session Overview This session adds an opt-in static Brief export for Trend Finder. The export turns the current validated Trend Finder payload into a standalone browser-safe report that can be opened outside the running AI OS app while preserving the same privacy, provenance, and source-compliance boundaries used by the dashboard Brief tab. The feature fills the documented gap between the dashboard-native Brief and a shareable read-only report. It must not copy the Outlier Lab default hosting, scheduled self-commit, or public deployment pattern. The default path remains a local generated export under the private Trend Finder cache, with any hosting or deployment guidance documented as optional operator work. The export is intentionally narrow. It should include safe summaries, source health, public evidence links, provenance labels, score/actionability labels, and bounded prediction/retro context. It must exclude prompts, provider responses, raw source dumps, private snapshots, private caches, raw logs, credentials, account auth, local triage notes, and private file paths. *** ## 2. Objectives 1. Add a CLI command that exports the current validated Trend Finder payload to an explicit generated static Brief directory. 2. Add script-side projection and fail-closed schema guards for a browser-safe static report payload. 3. Render a standalone HTML report with safe source, evidence, topic, provenance, prediction, retro, and optional asset reference sections. 4. Enforce path containment, private-data rejection, output atomicity, and unsafe asset fallback behavior. 5. Add focused CLI, schema, renderer, privacy, and browser smoke coverage plus docs that keep hosting opt-in. *** ## 3. Prerequisites ### Required Sessions * [x] `phase24-session01-source-local-scoring-signals` - Provides source-local ratio, actionability band, and pinned/promoted handling fields that the export can summarize without changing ranking. * [x] `phase24-session02-delta-aware-enrichment-spend-accounting` - Provides safe enrichment and spend summaries that the report can label without exposing private cache or billing internals. * [x] `phase24-session03-browser-safe-evidence-assets-file-hardening` - Provides hardened evidence asset metadata, manifest validation, and loopback bridge rules that any exported asset reference must respect. * [x] `phase24-session04-source-setup-target-configuration` - Provides reviewed source setup and source health state used in report trust summaries. * [x] `phase24-session05-scheduler-first-run-live-progress-controls` - Provides scoped run and scheduler context that can be summarized without raw logs or process internals. * [x] `phase24-session06-signal-workbench-local-triage` - Provides local triage state and docs proving triage annotations are browser-local only and must not be exported by default. ### Required Tools/Knowledge * Existing Trend Finder Brief display logic in `src/extensions/trend-finder/views/brief-view.tsx`. * Existing Trend Finder browser payload validation in `src/extensions/trend-finder/schema.ts`. * Existing evidence asset hardening helpers in `scripts/extensions/trend-finder/evidence-assets.ts` and the local asset bridge in `scripts/lib/trend-finder-asset-bridge.ts`. * Existing script CLI style in `scripts/trend-finder-backtest.ts` and `scripts/trend-finder-replay-backhistory.ts`. * Existing generated-data and private artifact rejection helpers in `scripts/lib/aggregate-live-data-write.ts`. * Existing E2E and fixture patterns under `tests/e2e/`. ### Environment Requirements * Bun 1.3.14 project toolchain from `.bun-version`. * Default live data path remains `src/data/live-data.json`, with `src/data/live-data.example.json` allowed for fixture-backed tests. * Default static export output lives under `.cache/extensions/trend-finder/static-brief/`, which is already ignored as generated private local state. * Custom output paths must be explicit, path-contained, and protected from writing outside the requested output root. *** ## 4. Scope ### In Scope (MVP) * Trend Finder operators can run a static Brief export command that reads the current generated live-data file, extracts `extensions.items["trend-finder"]`, validates it, and writes a standalone report to an explicit output directory. * The export command fails closed for missing live data, missing Trend Finder extension data, invalid Trend Finder payloads, invalid output paths, unsafe asset references, private field names, token-shaped strings, local home paths, raw logs, raw source dumps, account auth, and local triage notes. * The static report includes safe run metadata, source health, provenance labels, top topics, score/actionability labels, public evidence links, bounded prediction/retro context, spend labels, enrichment/asset summaries, and explicit fallback labels for unavailable or unsafe evidence assets. * The report renderer writes deterministic HTML, escaped inline data, safe browser-only interactivity, accessible sections, responsive layout, and no remote script dependencies. * Export writes are atomic enough for local use: create output directories, write temporary files, rename into place, and leave the previous export intact when validation fails before the final write. * Documentation explains the generated output directory, privacy exclusions, cache-header guidance for optional hosting, and why public deployment or generated artifact commits are not default workflows. ### Out of Scope (Deferred) * Public Vercel, Cloudflare Pages, or GitHub Pages deployment as a default workflow - *Reason: hosting remains an opt-in operator decision.* * Auto-committing generated reports, private runtime data, media assets, or cache files - *Reason: generated runtime artifacts remain local and ignored.* * Exporting local Workbench triage notes or hidden/visibility settings by default - *Reason: those are browser workflow annotations, not generated Trend Finder intelligence.* * Exporting raw transcripts, comments, provider responses, prompts, Actor inputs, Dataset rows, raw source payloads, billing payloads, account IDs, or private cache paths - *Reason: these are outside the browser-safe contract.* * Adding new source adapters, scheduler jobs, source setup writes, or new collection behavior - *Reason: this session consumes the current validated payload only.* *** ## 5. Technical Approach ### Architecture Create a script-side static export module that loads the AI OS live-data file, extracts the Trend Finder extension branch, validates it through the existing schema, projects it into a smaller `StaticBriefReport` contract, runs privacy and asset safety checks, and writes a deterministic output directory. Keep report projection separate from HTML rendering. The projection layer should choose bounded topic, evidence, source, prediction, retro, spend, enrichment, and asset summary rows. The renderer should receive only the safe contract, escape all interpolated text, serialize inline data safely, and produce a standalone report with no dependency on the running dev server. Default output should live below `.cache/extensions/trend-finder/static-brief/`. A custom output directory can be supported, but the implementation must resolve paths, reject traversal, and avoid serving or copying from private cache roots unless the file is an allowed asset already validated through the Session 03 manifest contract. ### Design Patterns * Script-only runtime boundary: the CLI handles live-data reads and static writes; browser code does not gain new access to private files. * Safe projection before rendering: convert `TrendFinderData` into a narrow report contract before creating HTML. * Fail-closed privacy checks: reject suspicious private fields or strings before writing the final report. * Bounded output: cap topics, evidence rows, source rows, prediction/retro rows, warnings, and summary strings so the report remains inspectable. * Atomic local writes: validate first, write temporary files second, rename final files last. * Optional hosting only: cache-header guidance belongs in docs or static metadata, not as an enabled deployment workflow. ### Technology Stack * TypeScript and Bun scripts. * Zod-backed Trend Finder schema validation through existing project helpers. * Node `fs/promises`, `path`, and deterministic string escaping helpers. * Vitest for projection, CLI, renderer, privacy, and path validation tests. * Playwright for one static HTML smoke test. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/trend-finder-export-brief.ts` | CLI entrypoint, argument parsing, env loading, dry-run mode, exit codes, and human/JSON summaries. | \~220 | | `scripts/extensions/trend-finder/static-brief-export.ts` | Live-data loading, Trend Finder extraction, safe report projection, privacy validation, output path resolution, and file writes. | \~520 | | `scripts/extensions/trend-finder/static-brief-renderer.ts` | Deterministic standalone HTML renderer, escaping helpers, inline-data serializer, and report asset metadata. | \~420 | | `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts` | Unit tests for projection, fail-closed checks, path containment, atomic writes, private-data rejection, and asset fallbacks. | \~360 | | `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Unit tests for HTML escaping, bounded rows, accessibility landmarks, inline JSON escaping, and no remote scripts. | \~240 | | `tests/e2e/trend-finder-static-brief.spec.ts` | Browser smoke test that opens an exported static report from fixture data and verifies layout, links, and privacy exclusions. | \~180 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `package.json` | Add `trend-finder:export-brief` script. | \~2 | | `src/extensions/trend-finder/fixtures.ts` | Add or adjust fixture rows for static export topics, source health, evidence assets, prediction/retro rows, spend, and unsafe-field test cases. | \~80 | | `docs/extensions/README_docs-extensions.md` | Update the extension docs summary to describe implemented static Brief export and privacy exclusions. | \~80 | | `docs/extensions/trend-finder-pipeline.md` | Document the export command, generated output root, fail-closed rules, asset/cache-header guidance, and opt-in hosting boundary. | \~160 | | `docs/extensions/trend-finder-ui-surfaces.md` | Update Brief/export behavior, excluded local triage/visibility state, and report inspection expectations. | \~120 | | `docs/extensions/trend-finder-runtime-and-provenance.md` | Document static export provenance labels, privacy checks, asset fallback behavior, and generated artifact boundaries. | \~120 | *** ## 7. Success Criteria ### Functional Requirements * [ ] `bun run trend-finder:export-brief` exports a standalone static report from valid Trend Finder live data into an explicit generated directory. * [ ] The command supports a dry-run mode that validates inputs and reports projected counts without writing final output. * [ ] Missing live data, missing Trend Finder extension data, invalid payloads, path traversal, unsafe output roots, unsafe asset references, and private data patterns fail before final output is written. * [ ] The generated report renders safe run metadata, source health, top topics, score/actionability labels, public evidence links, provenance labels, bounded prediction/retro context, spend labels, enrichment counts, and asset fallback labels. * [ ] The report does not include raw prompts, provider responses, raw source dumps, raw transcripts, raw logs, Actor inputs, Dataset rows, credentials, account auth, private snapshots, private caches, local triage notes, token-shaped strings, or local private file paths. ### Testing Requirements * [ ] Unit tests written and passing for static report projection, privacy guards, path containment, asset reference handling, bounded rows, and fail-closed behavior. * [ ] Unit tests written and passing for deterministic HTML rendering, escaping, inline data safety, accessibility landmarks, and no remote script dependencies. * [ ] CLI tests written and passing for help, dry-run, invalid input, custom output, default output, write summaries, and exit-code behavior. * [ ] Browser smoke test written and passing for loading the exported report from fixture data and verifying that private strings do not appear. * [ ] Manual testing completed for opening the exported `index.html` on desktop and mobile-width viewports. ### Non-Functional Requirements * [ ] Static export remains opt-in and does not add a default hosted deployment or generated artifact commit path. * [ ] Generated output and any copied allowed assets stay under ignored local generated roots unless an operator explicitly chooses a custom output path. * [ ] Export output is deterministic for the same input payload except for explicit generated timestamps or run metadata. * [ ] The report remains usable with fixture data, missing optional evidence assets, degraded sources, deterministic fallback analysis, unavailable spend, and no prediction/retro archive. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. *** ## 8. Implementation Notes ### Key Considerations * The export should reuse `validateTrendFinderData` or the existing schema instead of parsing raw Trend Finder payloads ad hoc. * The static report can model the dashboard Brief but should not import React rendering code into the Bun CLI unless implementation proves that path is simpler and testable. * The CLI should report safe counts and output paths, but not raw private paths from source caches or logs. * The default generated output root should remain under `.cache/`, which is already ignored, to avoid a new gitignore dependency. * Asset references should be conservative. If an asset cannot be proven safe and report-local, the report should render the existing fallback label. ### Potential Challenges * Live-data payload includes only the extension branch inside a larger AI OS object: Extract the Trend Finder branch by extension ID and validate the extracted value before projection. * Asset bridge URLs require a dev token and cannot be used directly in a standalone report: Convert only validated, copied report-local assets or replace the asset with a fallback label. * Static HTML can accidentally leak raw serialized input: Render from a narrow report contract and scan final output before rename. * Custom output paths can escape the intended root: Resolve paths before writing and reject traversal, null bytes, and ambiguous roots. * Existing docs currently state generated HTML report output is not implemented: Update that language only after implementation lands. ### Relevant Considerations * \[P00] **Stack conventions**: Use Bun, TypeScript, Vite/TanStack-compatible repo patterns, and existing script/test conventions. * \[P02] **Extension payloads and demo labels stay bounded**: Export rows and strings must be capped and provenance labels must stay explicit. * \[P02] **New source adapters need per-source compliance review**: Do not add new source adapters or expose unreviewed source media. * \[P05] **Script-only runtime boundary**: Keep private live-data reads and static report writes in scripts, not browser UI. * \[P11] **Scheduler state/log privacy boundary**: Static reports can include safe scheduler labels, not raw scheduler logs or private paths. * \[P23] **Do not document planned features as implemented**: Docs should be updated to implemented static export only after the command works. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Export writes could overwrite or partially write files after validation fails. * Static HTML could include raw serialized private input instead of the safe report projection. * Asset URLs could point back to a loopback token-gated bridge or a private cache path that cannot be safely opened as a standalone report. * Custom output paths could escape the intended report directory. * Docs could imply public hosting or generated artifact commits are part of the default workflow. *** ## 9. Testing Strategy ### Unit Tests * Test projection from fixture `TrendFinderData` into bounded report rows. * Test missing, malformed, or invalid Trend Finder payloads fail closed. * Test private strings, token-like values, local paths, raw log fields, raw source dump fields, and local triage fields are rejected. * Test output path resolution rejects traversal, null bytes, escaped roots, and unsupported roots. * Test renderer escaping for HTML text, attributes, URLs, and inline JSON. ### Integration Tests * Test CLI dry-run and write flows against temporary fixture live-data files. * Test default output and custom output directory behavior. * Test report file summary, warnings, and final write behavior. * Test asset reference fallback and optional copied asset handling. ### Manual Testing * Run the export command against current generated live data. * Open the generated `index.html` directly in a browser. * Verify desktop and mobile-width layouts, evidence links, expand/collapse controls, focus order, and text fit. * Search the generated output for private path, token, raw log, prompt, provider response, Actor, Dataset, cache, and triage-note patterns. ### Edge Cases * No topics, no evidence, no sources, no watchlist, and no prediction/retro archive. * Fixture/demo provenance and deterministic fallback analysis. * Degraded/offline sources and unavailable spend. * Missing or unsafe evidence asset references. * Topic rows referencing missing evidence IDs. * Output directory already exists from a previous export. *** ## 10. Dependencies ### External Libraries * No new external libraries expected. ### Other Sessions * **Depends on**: Phase 24 sessions 01 through 06. * **Depended by**: `phase24-session08-cross-surface-documentation-reference-mode` and `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-session07-static-brief-export/spec.md?ask=&goal= ``` `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.