> 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-session12-brief-qa-markdown-export-and-kpi-strip/spec.md). # Session Specification **Session ID**: `phase28-session12-brief-qa-markdown-export-and-kpi-strip` **Phase**: 28 - Trend Finder Trends-Finderz Adoption **Status**: Not Started **Created**: 2026-06-14 *** ## 1. Session Overview This session strengthens the Trend Finder Brief as a shareable, browser-safe creator artifact. The existing static Brief exporter already projects a bounded report and writes `index.html` plus `manifest.json`; this session adds an explicit post-render QA layer that checks required sections, verifies meaningful content, scans rendered output and manifest data for private path or env-name leaks, and records the result in the export manifest. The session also makes the in-app Brief more useful for creator workflows by adding a copy-as-Markdown flow composed from the same safe Brief projection. The Markdown output should be clean enough to paste into notes, newsletters, or submission drafts without exposing local-only state. A small JSON export helper can reuse the same projection where it stays cheap and browser-safe. Finally, the Trends view gets a compact run-summary KPI strip derived from existing aggregates: topics, active sources, evidence rows, hidden gems, and run freshness. This keeps the first viewport aligned with the UX contract while avoiding new payload fields or collection behavior. *** ## 2. Objectives 1. Add a deterministic static Brief QA result with structural checks, leak scanning, manifest recording, and export failure on private leaks. 2. Surface the latest static Brief QA status in the Brief view export/status area without exposing local paths or raw generated artifacts. 3. Add a copy-as-Markdown action built from the same safe Brief projection, with accessible feedback and duplicate-trigger protection. 4. Add a compact Trends run-summary KPI projection and strip using existing aggregates only. *** ## 3. Prerequisites ### Required Sessions * [x] `phase24-session07-static-brief-export` - Static Brief export and browser-safe projection foundation exist. * [x] `phase28-session09-action-queue-surface` - Decisions Brief section is part of the static export QA surface. * [x] `phase28-session11-search-palette-and-deterministic-embeddings` - Current Trend Finder shell and view-model state are complete before this UI pass. ### Required Tools/Knowledge * Bun 1.3.14, TypeScript, Vitest, React 19, Tailwind CSS 4, lucide-react. * Existing static Brief export code in `scripts/extensions/trend-finder/static-brief-export.ts` and renderer code in `scripts/extensions/trend-finder/static-brief-renderer.ts`. * Existing Brief and Trends route components in `src/extensions/trend-finder/views/brief-view.tsx` and `src/extensions/trend-finder/views/trends-view.tsx`. * Existing Trend Finder projection helpers in `src/extensions/trend-finder/view-model.ts`. ### Environment Requirements * No live collector run, AI runtime credential, source credential, source adapter, or new third-party transfer is required. * Static export QA must run locally against projected report, rendered HTML, and manifest data. * Browser-visible copy/export actions must use safe in-memory Trend Finder data only and must not read local files directly. *** ## 4. Scope ### In Scope (MVP) * Trend Finder operators can validate generated static Brief output for required structure, non-empty top creator angles where data exists, and required decision/movement/source sections. * Static Brief export fails on private path fragments, private host URLs, browser-local storage keys, token-shaped fields, or configured env-name leaks in the report, rendered HTML, or manifest data. * The export manifest records a compact QA object with status, checked section counts, issue counts, warning counts, and generated timestamp. * The Brief view shows an export QA status line derived from safe projection data, including clear pass/warning/fail/unavailable labels. * Trend Finder users can copy the visible Brief as Markdown from the Brief view with clipboard denied/unavailable handling, accessible labels, and in-flight duplicate-trigger prevention. * A JSON export helper reuses the same safe Brief projection when it can be implemented without new payload fields or file-system access from the browser. * The Trends view shows a compact run-summary KPI strip for topic count, active source count, evidence row count, hidden gem count, and run freshness. * Tests cover QA structural checks, leak checks, manifest recording, Markdown composition, clipboard states, KPI projection, and existing export behavior. ### Out of Scope (Deferred) * Server-composed PDF export - *Reason: lower local value and no concrete need in the session stub.* * Full multi-template Reports Hub - *Reason: this session targets one Brief projection, not a report-management product.* * New Trend Finder payload fields for KPI data - *Reason: KPI values must derive from existing aggregates.* * New source adapters, source queries, keyword packs, or spend changes - *Reason: compliance-gated collection work belongs to Sessions 13 and 14.* * Hosted report upload, public sharing API, or cloud storage - *Reason: current operation remains local self-use.* *** ## 5. Technical Approach ### Architecture Add a static Brief QA module that accepts the projected `StaticBriefReport`, the rendered HTML string, and the manifest candidate. It returns a bounded QA result with deterministic issue codes, severity, checked sections, and display-safe messages. Export execution runs QA after render and before atomic output promotion; blocking failures throw `StaticBriefExportError` and preserve any existing output directory. Keep browser copy/export behavior on the same projection boundary. Shared helpers in the Trend Finder view-model layer can project a safe creator Brief document from parsed Trend Finder data, then render Markdown and JSON strings from that document. The Brief view consumes those helpers and manages clipboard state locally with reset-on-retry behavior. For the Trends KPI strip, add a small run-summary projection helper that derives display labels and tones from ranked topics, hidden gems, source health, evidence count, and `lastUpdatedAt`. The Trends view renders those projected rows using existing dense dashboard styling, tabular numbers, and accessible labels. ### Design Patterns * Project before rendering: QA, Markdown, JSON, and KPI UI consume safe projection objects rather than raw local artifacts. * Fail closed on privacy: leak findings block static export and do not promote partial output. * Bounded lists: QA issues, Markdown sections, JSON fields, and KPI rows use explicit limits and deterministic ordering. * Existing primitives: Use local buttons, Tailwind conventions, lucide icons, and current Trend Finder view structure rather than adding UI dependencies. * Deterministic fallback: When Brief data is sparse, output explicit unavailable or empty states instead of inventing metrics. ### Technology Stack * TypeScript 6, Bun 1.3.14, Vitest, happy-dom component tests. * React 19, existing Trend Finder route components, lucide-react icons. * Node file-system writes remain isolated to the static export script. * Browser clipboard uses `navigator.clipboard.writeText` with fallback/error states and no direct file-system access. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- | ---------- | | `scripts/extensions/trend-finder/static-brief-qa.ts` | Deterministic QA result builder, structural checks, leak scanner, and issue-code contracts. | \~240 | | `scripts/extensions/trend-finder/__tests__/static-brief-qa.test.ts` | Focused QA tests for structure, leak detection, limits, and deterministic issue ordering. | \~180 | | `src/extensions/trend-finder/brief-export-model.ts` | Browser-safe Brief document projection plus Markdown and JSON string composers. | \~260 | | `src/extensions/trend-finder/__tests__/brief-export-model.test.ts` | Projection, Markdown, JSON, escaping, empty-state, and privacy-boundary tests. | \~180 | ### Files to Modify | File | Changes | Est. Lines | | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | ---------- | | `scripts/extensions/trend-finder/static-brief-export.ts` | Run QA before writes, record QA result in report/manifest, and fail closed on blocking issues. | \~160 | | `scripts/extensions/trend-finder/static-brief-renderer.ts` | Preserve required section anchors and expose render markers needed by QA without leaking internals. | \~40 | | `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts` | Assert manifest QA object, failure on private leaks, and output preservation on QA failure. | \~120 | | `src/extensions/trend-finder/view-model.ts` | Add run-summary KPI projection and any shared safe labels used by Brief export composition. | \~140 | | `src/extensions/trend-finder/views/brief-view.tsx` | Add QA status line, copy Markdown action, optional JSON copy/download action, feedback states, and visibility menu entry. | \~220 | | `src/extensions/trend-finder/views/trends-view.tsx` | Replace ad hoc KPI row with run-summary KPI projection including run freshness. | \~100 | | `src/extensions/trend-finder/views/__tests__/brief-view.test.tsx` | Cover QA status, Markdown clipboard success/failure, duplicate-trigger prevention, and state reset. | \~180 | | `src/extensions/trend-finder/__tests__/view-model.test.ts` | Cover run-summary KPI values, tones, freshness labels, and sparse payload behavior. | \~120 | | `src/extensions/trend-finder/fixtures.ts` | Add fixture coverage for QA warnings, creator-angle Markdown, and stale/fresh KPI states. | \~80 | | `docs/extensions/trend-finder-ui-surfaces.md` | Document Brief Markdown copy, export QA status, and KPI strip behavior as shipped UI. | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Static Brief export validates required sections, top creator-angle content, source health rows, movement groups, decisions, evidence, and generated manifest metadata before final output is promoted. * [ ] A private path fragment, private host URL, local-storage key, token-shaped field, or env-name leak in report, rendered HTML, or manifest data blocks the export and leaves the previous output intact. * [ ] Manifest JSON includes a bounded QA result with status, generated time, checked section count, issue counts, warning counts, and display-safe issue summaries. * [ ] Brief view surfaces export QA as pass/warning/fail/unavailable status without showing local paths or raw internal issue payloads. * [ ] Copy Brief as Markdown uses the same safe projection as the Brief view, handles clipboard denied/unavailable states, prevents duplicate writes while pending, and resets feedback when retried or data changes. * [ ] Optional JSON export/copy uses the same safe projection and excludes raw prompts, private paths, local triage notes, cache keys, and source dumps. * [ ] Trends view shows topics, active sources, evidence rows, hidden gems, and run freshness in a compact, accessible, responsive KPI strip derived from existing data. ### Testing Requirements * [ ] Unit tests cover QA structural checks, privacy leaks, manifest recording, deterministic ordering, and export failure behavior. * [ ] Unit tests cover Markdown and JSON composition, escaping, sparse-data output, and private-string exclusion. * [ ] Component tests cover Brief QA status rendering, clipboard success, clipboard failure, duplicate-trigger prevention, and feedback reset. * [ ] View-model tests cover run-summary KPI projection, freshness labels, tones, and empty/sparse payload fallback. * [ ] Focused test commands pass or unrelated existing failures are documented in implementation notes. ### Non-Functional Requirements * [ ] No new dependency, source adapter, credential flow, hosted storage path, or network transfer is introduced. * [ ] Browser-visible payload and generated static output continue to exclude raw prompts, provider responses, local private paths, source dumps, and token-shaped strings. * [ ] KPI and copy/export UI remains dense, keyboard reachable, and responsive without pushing the ranked trend surface below the first viewport. ### Quality Gates * [ ] All files ASCII-encoded. * [ ] Unix LF line endings. * [ ] Code follows project conventions. * [ ] `bun run test` or focused Vitest commands pass for touched areas. *** ## 8. Implementation Notes ### Key Considerations * `collectStaticBriefPrivacyIssues` already exists in the exporter; this session should consolidate or reuse that behavior in the QA module instead of creating inconsistent leak rules. * Static export currently validates privacy before writing and uses atomic output promotion. QA failures must preserve that failure mode. * Existing Trends view already has a KPI row; the session should improve the projection and freshness coverage without creating a larger hero surface. * The Brief view should expose copy/export actions as real controls with labels, focus states, and feedback rather than passive descriptive text. ### Potential Challenges * Manifest schema drift: Keep the QA object additive and bounded so existing manifest consumers remain compatible. * Browser clipboard variance: Treat denied or missing clipboard APIs as a normal error state and keep the Markdown string accessible to retry logic. * False-positive leak scans: Use explicit issue codes and bounded patterns so env-name and private-path detection is strict enough to catch regressions without rejecting harmless public evidence text. * Sparse reports: Required-section QA should distinguish missing structure from legitimately empty data and report warnings instead of blocking where the export is still safe. ### Relevant Considerations * \[P24] **Browser-safe export and triage boundaries**: Static Brief output must keep local triage notes, private paths, and raw evidence out of exported or browser-visible output. * \[P27] **Trend Finder payload growth needs release checks**: Brief export, private-artifact scans, payload budget, and Reference mode remain one release surface. * \[P24] **Project before rendering**: The Markdown and JSON flows should be backed by a narrowed browser-safe projection before string composition. * \[P27] **Reference manuals track shipped behavior only**: Documentation updates must describe only the QA, Markdown, and KPI behavior that lands in this session. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Export QA reports pass while rendered HTML or manifest still leaks private local data. * Copy-as-Markdown can be triggered repeatedly, leaves stale success/error state, or fails silently when clipboard permissions are denied. * KPI values drift from source payload meaning because they are computed ad hoc in route components rather than a tested projection helper. *** ## 9. Testing Strategy ### Unit Tests * Test static Brief QA issue generation for missing required sections, empty top angle rows, private path fragments, env-name leaks, local-storage keys, and deterministic ordering. * Test `runStaticBriefExport` manifest QA recording, blocking QA failure, and output preservation when a failure occurs. * Test Markdown and JSON composition over fixture data, legacy/sparse payloads, escaped Markdown special characters, and private-string exclusion. * Test run-summary KPI projection for fresh, stale, empty, degraded-source, and no-evidence payload states. ### Integration Tests * Extend static Brief export tests to render HTML, build manifest, run QA, and assert that the manifest includes only safe QA labels. * Extend Brief view component tests to exercise clipboard success and failure states with mocked `navigator.clipboard`. ### Manual Testing * Open the Brief view with fixture data and verify the QA status, Markdown copy button, JSON action if included, and visibility controls remain usable. * Open the Trends view at desktop and mobile review sizes and confirm the KPI strip stays compact, readable, and above the ranked trend surface. * Run `bun run trend-finder:export-brief -- --dry-run --json` and verify QA summary fields appear without local paths. ### Edge Cases * Clipboard API missing, denied, or rejects after the copy button is pressed. * Static Brief contains no ranked topics but has safe source/evidence metadata. * Generated report includes public URLs that resemble private hostnames in text. * Existing output directory contains a prior export when QA fails. * Data changes while a copy feedback state is visible. *** ## 10. Dependencies ### External Libraries * No new external libraries. ### Other Sessions * **Depends on**: `phase24-session07-static-brief-export`, `phase28-session09-action-queue-surface`, `phase28-session11-search-palette-and-deterministic-embeddings` * **Depended by**: `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-session12-brief-qa-markdown-export-and-kpi-strip/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.