> 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/phase29-session13-static-brief-archival-and-richness/spec.md).

# Session Specification

**Session ID**: `phase29-session13-static-brief-archival-and-richness` **Phase**: 29 - Trend Finder TrendingAI Comparison Adoption **Status**: Not Started **Created**: 2026-06-21

***

## 1. Session Overview

This session improves the generated Trend Finder static Brief as a local human-readable artifact. It adds an opt-in archival mode that writes a run-numbered export and a `latest.html` pointer so operators can compare Briefs between runs without changing the existing data snapshot or collection posture.

The default export path remains backwards-compatible: when archival is not enabled, `bun run trend-finder:export-brief` continues to write `index.html`, `manifest.json`, and report-local assets under the selected output directory. Archival mode is an additional write shape over the same validated, privacy scanned report projection.

The richness work uses fields that already exist from prior Phase 29 sessions, especially attention and polarity rows, aggregate reception, and per-evidence rationale. The static Brief should become denser and easier to diff, but it must keep the deliberate media gap: no social embeds, thumbnails, transcripts, or unreviewed media are inlined into the report.

***

## 2. Objectives

1. Add opt-in run-numbered static Brief archival with a `latest.html` pointer.
2. Preserve the current default `index.html` and `manifest.json` export behavior when archival is disabled.
3. Increase static Brief density using existing published attention, reception, polarity, corroboration, and evidence-rationale fields.
4. Keep static Brief output privacy-clean, browser-safe, and media-embed free.
5. Prove archival, default compatibility, renderer richness, QA, and e2e behavior with focused tests.

***

## 3. Prerequisites

### Required Sessions

* [x] `phase29-session02-attention-pattern-and-polarity-grid` - Provides the attention and polarity fields used for richer Brief presentation.
* [x] `phase29-session03-reception-signal-aggregate-only` - Provides aggregate reception fields and confirms the no-comment-body boundary.
* [x] `phase29-session05-per-evidence-rationale` - Provides bounded per-evidence rationale fields for denser evidence rows.
* [x] `phase28-session12-brief-qa-markdown-export-and-kpi-strip` - Provides the static Brief export, QA, and privacy-scan baseline.

### Required Tools/Knowledge

* Bun 1.3.14 workflow through `bun run test`.
* Existing static Brief exporter, renderer, QA, and CLI in `scripts/`.
* Existing Playwright static Brief e2e coverage in `tests/e2e/`.
* Current Trend Finder browser-safe payload, source boundary, and payload budget rules.

### Environment Requirements

* Project dependencies installed with Bun.
* A generated or fixture-backed Trend Finder payload for export tests.
* No new credential, source, media, database, hosted storage, dependency, or third-party transfer approval is required.

***

## 4. Scope

### In Scope (MVP)

* Operators can enable archival for a static Brief export - Add an explicit opt-in flag or option that writes a numbered run artifact and updates a `latest.html` pointer.
* Operators keep the existing default export - Preserve current output paths, summaries, CLI behavior, and atomic promotion when archival is disabled.
* Operators can diff human-readable Briefs across runs - Use stable run numbering, manifest metadata, and deterministic ordering for archive outputs.
* Static Brief readers see denser topic context - Render already-published attention, reception, polarity, corroboration, and evidence-rationale fields without adding new source collection.
* Static Brief remains privacy-clean - Continue to reject private paths, raw prompts, provider responses, raw source dumps, local triage notes, tokens, credential-shaped strings, and browser-storage keys.
* Static Brief keeps the media-embed gap - Do not inline social embeds, thumbnails, transcripts, video, audio, iframe content, or unreviewed media.
* Tests prove archival and compatibility - Cover archive writes, latest pointer updates, default export compatibility, renderer richness, privacy cleanliness, and e2e opening of the archived report.

### Out of Scope (Deferred)

* Changing snapshot or data-history storage - Reason: snapshots already preserve data history, and this session is only about the human-readable artifact.
* New source, social, podcast, media, transcript, or asset collection - Reason: this session uses only already-published fields.
* Public hosting, deployment, CDN headers, or committed generated reports - Reason: hosting remains operator-managed and generated reports stay local.
* One-to-Watch, pre-run estimate, podcast compliance, or podcast themes work - Reason: later Phase 29 sessions own those areas.
* Inlining media assets in the report - Reason: copied assets may remain linked or represented by fallback labels, but not embedded as unreviewed media.

***

## 5. Technical Approach

### Architecture

Add a small archival helper under `scripts/extensions/trend-finder/` to keep run number discovery, archive path validation, pointer rendering, and path-safe write planning separate from the already large exporter. The helper should derive the next `run-0001` style directory from existing archive entries, reject unsafe path segments, and produce a `latest.html` pointer that links to the newest archived `index.html` using only relative public report paths.

Extend `runStaticBriefExport` with an opt-in archive option while keeping the current default path unchanged. Default mode should still resolve one output root and atomically promote `index.html`, `manifest.json`, and copied assets. Archive mode should use the same validated report, rendered HTML, manifest QA, privacy scan, and duplicate-output lock, then atomically write the run directory and update the latest pointer only after QA succeeds.

The richer report should stay within the existing `StaticBriefReport` projection style: bounded strings, stable arrays, strict Zod schemas, explicit empty states, and renderer escaping. Use existing view-model fields rather than reading raw payload branches in the renderer. QA should reject missing archive metadata when archive mode is enabled and should fail closed if rendered HTML contains media embeds or private strings.

### Design Patterns

* Additive option: archival is opt-in and cannot change default output.
* Atomic write path: validate, render, scan, write temp output, then promote.
* Stable local artifact names: run directories increment deterministically.
* Browser-safe projection: renderer consumes bounded report fields only.
* No media embed policy: links and fallback labels are allowed; inline media is not.
* Fail closed on privacy or QA issues: preserve any previous output on failure.

### Technology Stack

* TypeScript for exporter, helper, CLI, QA, and renderer code.
* Zod schemas for strict report and manifest projection.
* Bun and Vitest for focused script tests.
* Playwright for static Brief browser/e2e validation.
* Existing project scripts for typecheck, payload budget, and private-artifact scans.

***

## 6. Deliverables

### Files to Create

| File                                                                     | Purpose                                                      | Est. Lines |
| ------------------------------------------------------------------------ | ------------------------------------------------------------ | ---------- |
| `scripts/extensions/trend-finder/static-brief-archive.ts`                | Archive naming, path safety, latest pointer, write planning. | \~220      |
| `scripts/extensions/trend-finder/__tests__/static-brief-archive.test.ts` | Unit tests for archive numbering, pointer output, and paths. | \~180      |

### Files to Modify

| File                                                                      | Changes                                                                     | Est. Lines |
| ------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ---------- |
| `scripts/extensions/trend-finder/static-brief-export.ts`                  | Add archive options, summary fields, manifest metadata, richer projection.  | \~180      |
| `scripts/extensions/trend-finder/static-brief-renderer.ts`                | Render denser topic/evidence context and archive metadata without embeds.   | \~160      |
| `scripts/extensions/trend-finder/static-brief-qa.ts`                      | Add archive pointer checks and media-embed rejection.                       | \~90       |
| `scripts/trend-finder-export-brief.ts`                                    | Add CLI parsing, help, JSON summary, and error output for archive mode.     | \~90       |
| `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`   | Cover default compatibility, archive writes, manifests, and failure safety. | \~180      |
| `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` | Cover richer rendering, escaping, and no media embeds.                      | \~100      |
| `scripts/extensions/trend-finder/__tests__/static-brief-qa.test.ts`       | Cover archive metadata QA, pointer validation, and embed rejection.         | \~90       |
| `tests/e2e/trend-finder-static-brief.spec.ts`                             | Cover archived report opening, latest pointer, privacy, and mobile layout.  | \~80       |
| `docs/extensions/trend-finder-pipeline.md`                                | Document archive mode, latest pointer, default compatibility, and privacy.  | \~60       |
| `docs/commands.md`                                                        | Document CLI archive flag and output shape.                                 | \~40       |

***

## 7. Success Criteria

### Functional Requirements

* [ ] Archive mode writes a numbered static Brief run artifact and a `latest.html` pointer.
* [ ] Default export behavior remains compatible when archival is disabled.
* [ ] Archive manifests identify the run number, latest pointer, source run ID, QA status, and report file paths.
* [ ] Static Brief topic and evidence sections include richer context from existing attention, reception, polarity, corroboration, and rationale fields.
* [ ] The renderer inlines no social embeds, thumbnails, transcripts, video, audio, iframe content, or unreviewed media.
* [ ] Failed QA or privacy scans preserve existing output and do not promote a new latest pointer.

### Testing Requirements

* [ ] Unit tests written and passing for archival path planning and pointer generation.
* [ ] Exporter tests prove archive mode, default compatibility, manifests, failure safety, and privacy cleanliness.
* [ ] Renderer and QA tests prove dense fields render safely and media embeds fail closed.
* [ ] Playwright e2e opens an archived report through `latest.html` and checks desktop and mobile overflow.
* [ ] Manual testing completed for dry-run, default write, and archive write commands.

### Non-Functional Requirements

* [ ] Static Brief report projection remains bounded and browser-safe.
* [ ] Existing 1 MB Trend Finder payload budget remains green.
* [ ] Generated `.cache/` reports remain ignored and untracked.
* [ ] Archive mode uses atomic writes and duplicate-trigger prevention while in-flight.

### Quality Gates

* [ ] All files ASCII-encoded.
* [ ] Unix LF line endings.
* [ ] Code follows project conventions.
* [ ] Focused tests and relevant typecheck commands pass.

***

## 8. Implementation Notes

### Key Considerations

* Keep `runStaticBriefExport({ dryRun: true })` deterministic and write-free.
* Do not make archive mode the default or silently change existing output directory semantics.
* Prefer relative archive links so generated reports can move as a local directory without leaking private absolute paths.
* Treat `latest.html` as a pointer, not an embedded copy of the report, so there is one archived run artifact per run.
* Do not read browser localStorage, Workbench triage notes, raw source payloads, private caches, or raw logs for richer static Brief content.

### Potential Challenges

* Archive numbering collisions: Resolve by scanning only validated `run-0001` style directory names and writing through the existing duplicate-output lock.
* Latest pointer failure after run write: Use a temp pointer and promote it atomically, preserving the previous pointer if promotion fails.
* Asset path portability: Keep report-local asset links relative to each run directory and prevent traversal through path containment checks.
* Richness versus payload limits: Use existing bounded report fields and avoid adding raw topic or evidence branches to inline JSON.

### Relevant Considerations

* \[P02] **Extension payloads and labels stay bounded**: Keep the 1 MB payload limit and explicit live, fixture, fallback, degraded, blocked, and unavailable labels.
* \[P24] **Browser-safe export and triage boundaries**: Static Brief must keep local triage notes, private paths, raw evidence, prompts, provider responses, and browser-storage keys out of exported output.
* \[P27] **Repo-wide formatting drift remains**: Run focused formatting or ASCII checks only for session-touched files unless a broader cleanup is explicitly requested.
* \[P28] **Trend Finder release validation is bundled**: Static Brief export, private-artifact scan, payload budget, and docs updates should remain easy to record together during phase closeout.
* \[P00] **Do not document planned features as implemented**: Update docs only for behavior that the implementation actually ships.

### Behavioral Quality Focus

Checklist active: Yes

Top behavioral risks for this session:

* Archive mode could overwrite or orphan the previous latest pointer after a failed write.
* Default export behavior could regress while adding the archive path.
* Denser static Brief rendering could accidentally expose private strings or media embeds.
* Archive links could leak absolute filesystem paths or use unsafe traversal.

***

## 9. Testing Strategy

### Unit Tests

* Test archive numbering with empty archives, existing run directories, gaps, and ignored invalid names.
* Test pointer HTML generation uses escaped relative links and no private paths.
* Test path containment rejects traversal, absolute private labels, and unsafe archive roots.

### Integration Tests

* Test `runStaticBriefExport` default mode still writes only `index.html`, `manifest.json`, and report-local assets to the selected output directory.
* Test archive mode writes a numbered run directory, archive manifest metadata, copied assets, and `latest.html`.
* Test QA or privacy failures preserve the previous archived run and previous latest pointer.
* Test CLI parsing, help output, JSON summary, and redacted errors for archive mode.

### Manual Testing

* Run `bun run trend-finder:export-brief -- --dry-run --json`.
* Run `bun run trend-finder:export-brief -- --output <temp-dir>`.
* Run `bun run trend-finder:export-brief -- --output <temp-dir> --archive`.
* Open the generated latest pointer and verify it reaches the newest archived report.

### Edge Cases

* Missing live data, invalid Trend Finder payload, required-derived-field failures, and QA failures.
* Existing output directory with previous default export files.
* Existing archive with invalid directory names, gaps, or a stale latest pointer.
* Evidence rows with unsafe URLs, unavailable assets, or private-looking text.
* Mobile viewport overflow in the denser report sections.

***

## 10. Dependencies

### External Libraries

* None. Use Node/Bun standard library APIs and existing project dependencies.

### Other Sessions

* **Depends on**: `phase29-session02-attention-pattern-and-polarity-grid`, `phase29-session03-reception-signal-aggregate-only`, `phase29-session05-per-evidence-rationale`
* **Depended by**: `phase29-session18-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/phase29-session13-static-brief-archival-and-richness/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.