> 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/phase27-session12-documentation-validation-and-release/spec.md). # Session Specification **Session ID**: `phase27-session12-documentation-validation-and-release` **Phase**: 27 - Trend Finder Alpha Radar Adoption **Status**: Not Started **Created**: 2026-06-13 *** ## 1. Session Overview This session closes Phase 27 by aligning the committed Trend Finder manuals with the behavior shipped across Sessions 01-11, running the full validation suite, completing the security review, and recording the durable release decisions. It does not add new features; it proves and documents the Alpha Radar adoption work already completed in the phase. The main product outcome is trust in the upgraded Trend Finder surface. Engine Replay Reference mode imports committed Markdown manuals, so those files must describe actual behavior only: movement groups, calibration, derived signals, radar, watching state, sparklines, velocity dynamics, lifecycle stages, convergence, dated predictions, Story Log, competitor lens fields, angle packs, demand centers, themes, and outlier ideas. The session also performs the safe cleanup promised by the phase PRD. The old `docs/ongoing-projects/alpha-radar.md` file can be deleted only after a coverage check confirms that its mapping items, deferred source candidates, non-goals, and "do not regress" areas are preserved in Phase 27 artifacts and current documentation. *** ## 2. Objectives 1. Update the Trend Finder reference manuals so they match shipped Phase 27 behavior and remain renderable through Engine Replay Reference mode. 2. Record deferred source candidates, explicit non-goals, and do-not-regress areas as durable current documentation instead of an ongoing-project note. 3. Run full validation, static Brief export validation, privacy checks, and payload budget review for the completed Phase 27 surface. 4. Complete the security/compliance closeout, carryforward notes, and safe deletion of `docs/ongoing-projects/alpha-radar.md`. *** ## 3. Prerequisites ### Required Sessions * [x] `phase27-session01-brief-movement-groups-and-calibration-metrics` - Brief movement groups, today's pick, confidence bands, and calibration metrics are implemented. * [x] `phase27-session02-deterministic-derived-signals-and-risk-flags` - Saturation, gem score, consensus ratio, role share, and risk flags are implemented. * [x] `phase27-session03-data-driven-radar-aliases-and-watching-state` - Data-driven radar, aliases, watching state, and outlier preset are implemented. * [x] `phase27-session04-daily-time-series-persistence-and-sparklines` - Daily series, sparklines, and Hugging Face deltas are implemented. * [x] `phase27-session05-velocity-dynamics-upgrade` - Acceleration, significance, and burst dynamics are implemented. * [x] `phase27-session06-lifecycle-stage-taxonomy` - Lifecycle stages are implemented. * [x] `phase27-session07-convergence-detection-and-trajectory-visuals` - Convergence and score trajectory visuals are implemented. * [x] `phase27-session08-dated-predictions-and-story-log` - Dated predictions, target-date retros, and Story Log are implemented. * [x] `phase27-session09-competitor-lens-and-creator-angle-pack` - Competitor lens fields and richer creator angles are implemented. * [x] `phase27-session10-demand-centers` - Demand clusters are implemented. * [x] `phase27-session11-theme-rollups-and-outlier-ideas` - Theme rollups, outlier ideas, and embedding fallback ADR are implemented. ### Required Tools/Knowledge * Bun 1.3.14, TypeScript, Vitest, Playwright, Prettier, and project scripts from `package.json`. * Current Trend Finder manual registry in `src/extensions/trend-finder/reference-docs.ts`. * Phase 27 PRD and session artifacts under `.spec_system/PRD/phase_27/` and `.spec_system/specs/phase27-session*/`. * Existing privacy and private-artifact checks, static Brief export workflow, and extension payload budget limit. ### Environment Requirements * No new public source adapters or live source expansion. * No live AI runtime or source credentials are required for documentation and fallback validation. * Generated private artifacts, caches, reports, traces, and local data stay ignored and out of commits. *** ## 4. Scope ### In Scope (MVP) * Trend Finder operators can read current manuals - Update scoring, history, UI, creator lens, pipeline, runtime/provenance, sources, concepts, and extension README docs to describe actual Phase 27 behavior only. * Engine Replay can render current manuals - Verify or update the reference docs registry and docs links so in-app Reference mode still imports every manual. * Reviewers can trace Alpha Radar migration decisions - Preserve deferred source candidates, explicit non-goals, and do-not-regress areas in durable docs before deleting the old ongoing-project file. * Maintainers can trust release readiness - Run full typecheck, script typecheck, test, format check, e2e, static Brief export, private-artifact, and payload budget checks. * Security posture stays current - Review changed bridge surfaces and schema branches, update `.spec_system/SECURITY-COMPLIANCE.md`, and record carryforward notes in `.spec_system/CONSIDERATIONS.md`. ### Out of Scope (Deferred) * New Trend Finder features or behavior changes - *Reason: this is a closeout session; validation findings become follow-ups unless required to unblock release.* * Deferred source adapters such as Semantic Scholar, Bluesky, Replicate, newsletter targets, X/Twitter, or Digg - *Reason: each requires a future compliance-first phase.* * New media exposure or hotlinked thumbnails - *Reason: media remains compliance-gated and outside Phase 27 closeout.* * Replacing snapshot persistence with SQLite - *Reason: the SQLite transition remains a separate ongoing project.* *** ## 5. Technical Approach ### Architecture Build a source-to-doc coverage matrix from the Phase 27 PRD, Session 12 stub, and implementation/validation artifacts from Sessions 01-11. Use the matrix to update only committed documentation and reference metadata. The manuals remain the source of truth for Engine Replay Reference mode; browser code should not gain a dynamic documentation loader. Run validation in layers: static documentation checks first, focused Trend Finder runtime/export checks next, then full project quality gates. Record command outputs and any residual non-blocking risks in `implementation-notes.md`. If validation exposes a feature defect, fix only release-blocking issues that are necessary to keep documented behavior true; otherwise record the follow-up. Complete release hygiene by updating the security/compliance ledger and considerations with the Phase 27 result, then remove `docs/ongoing-projects/alpha-radar.md` only after confirming its contents are covered by Phase 27 artifacts and current docs. ### Design Patterns * Docs follow implementation: document shipped behavior, not planned or hoped behavior. * Committed Markdown as authority: Reference mode imports curated manuals from source files. * Project before rendering: Static Brief export and Reference mode stay on browser-safe projections and committed docs. * Compliance-first source expansion: deferred adapters remain documented candidates, not hidden implementation work. * Validation before deletion: remove the old ongoing-project file only after a coverage check. ### Technology Stack * Markdown documentation under `docs/extensions/`. * TypeScript reference registry under `src/extensions/trend-finder/reference-docs.ts`. * Bun scripts, TypeScript, Vitest, Playwright, Prettier, and existing shell checks. * Spec-system closeout artifacts under `.spec_system/specs/` and `.spec_system/`. *** ## 6. Deliverables ### Files to Create | File | Purpose | Est. Lines | | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | ---------- | | `.spec_system/specs/phase27-session12-documentation-validation-and-release/implementation-notes.md` | Record documentation coverage, validation commands, release notes, and follow-ups during implementation. | \~180 | | `.spec_system/specs/phase27-session12-documentation-validation-and-release/security-compliance.md` | Session security and GDPR review for docs, bridge-surface review, schema branches, export privacy, and deletion. | \~140 | | `.spec_system/specs/phase27-session12-documentation-validation-and-release/validation.md` | Validate task completion, docs coverage, commands, privacy checks, and release readiness. | \~180 | ### Files to Modify | File | Changes | Est. Lines | | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `docs/extensions/trend-finder-scoring.md` | Document saturation, gem score, consensus ratio, builder signal, risk flags, acceleration, significance, burst, and caps. | \~120 | | `docs/extensions/trend-finder-history.md` | Document daily series, dated predictions, target-date retros, Story Log, and calibration metrics. | \~120 | | `docs/extensions/trend-finder-ui-surfaces.md` | Document movement Brief, today's pick, data-driven radar, watching state, outlier preset, sparklines, convergence, Story Log, demand panel, themes, and outlier ideas. | \~180 | | `docs/extensions/trend-finder-creator-lens.md` | Document competitor list field, validation, save/rerun behavior, and angle-pack influence. | \~80 | | `docs/extensions/trend-finder-pipeline.md` | Document new pipeline stages, private state locations, export checks, and implementation map outcomes. | \~140 | | `docs/extensions/trend-finder-runtime-and-provenance.md` | Document new analyst fields, fallback behavior, derived-label provenance, and validator boundaries. | \~120 | | `docs/extensions/trend-finder-sources.md` | Document deferred source candidates pointer and Hugging Face delta behavior. | \~90 | | `docs/extensions/trend-finder-concepts.md` | Document lifecycle stage, convergence, demand cluster, theme, watching state, and related core objects. | \~100 | | `docs/extensions/README_docs-extensions.md` | Update current behavior list, certification commands, and manual links. | \~100 | | `src/extensions/trend-finder/reference-docs.ts` | Verify or update Reference mode labels/descriptions/source paths for changed manuals. | \~40 | | `.spec_system/SECURITY-COMPLIANCE.md` | Add Phase 27 closeout security/GDPR notes and validation result. | \~80 | | `.spec_system/CONSIDERATIONS.md` | Add carryforward lessons, active concerns, and any deferred follow-ups from Phase 27. | \~80 | | `docs/ongoing-projects/alpha-radar.md` | Delete after coverage check proves zero information loss. | deletion | *** ## 7. Success Criteria ### Functional Requirements * [ ] Trend Finder manuals document actual shipped Phase 27 behavior only. * [ ] Engine Replay Reference mode can render the updated manuals through the existing registry. * [ ] Deferred source candidates, explicit non-goals, and do-not-regress areas survive in durable docs. * [ ] `docs/ongoing-projects/alpha-radar.md` is deleted after coverage is verified. * [ ] Security/compliance and carryforward docs reflect the Phase 27 closeout. ### Testing Requirements * [ ] `bun run typecheck` passes. * [ ] `bun run typecheck:scripts` passes. * [ ] `bun run test` passes. * [ ] `bun run format:check` passes or any existing non-session drift is recorded with scoped formatting proof. * [ ] `bun run test:e2e` passes or any environment blocker is recorded with evidence. * [ ] Static Brief export and private-artifact checks pass. ### Non-Functional Requirements * [ ] Browser-safe payload boundary remains intact. * [ ] Extension payload remains under the shared 1 MB limit. * [ ] No raw prompts, provider responses, credentials, private cache paths, raw logs, local triage notes, or raw source dumps are documented as browser output. * [ ] No new dependency, source adapter, public transfer path, or bridge write surface is introduced. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions *** ## 8. Implementation Notes ### Key Considerations * The docs should distinguish AI OS host behavior from Trend Finder extension behavior and should keep source expansion explicitly compliance-gated. * `docs/ongoing-projects/alpha-radar.md` is safe to delete only after the mapping, deferred adapters, non-goals, and do-not-regress areas are covered in committed phase/docs artifacts. * Reference mode renders committed Markdown, so doc links and registry entries need verification after updates. * Full validation may be expensive; record exact commands and outcomes so the closeout is auditable. ### Potential Challenges * Manuals can drift into planned behavior: Use implementation artifacts and validation reports as the source of truth. * Repo-wide format or e2e checks may expose unrelated drift: Fix session-owned issues; record unrelated blockers without rewriting unrelated files. * Static Brief export can generate private local files: keep outputs in ignored cache locations and verify private-artifact checks. * Payload budget checks may need a populated fixture: use existing bounded example or generated-safe payload paths, not private raw caches. ### Relevant Considerations * \[P00] **Do not document planned features as implemented**: This session is primarily a docs truthfulness pass. * \[P02] **Extension payloads and demo labels stay bounded**: Payload budget and provenance labels must be rechecked after the new Phase 27 fields. * \[P02] **New source adapters need per-source compliance review**: Deferred source candidates stay documented, not implemented. * \[P24] **Browser-safe export and triage boundaries**: Static Brief and local triage state must not expose private notes, paths, or raw evidence. * \[P23] **Backlog migration into phase PRD**: Source anchors plus no-action decisions enable safe deletion of an old ongoing-project file. * \[P24] **Committed Markdown as authority**: Reference mode tests and docs checks should treat committed Markdown as the canonical manuals. * \[P25] **Final docs need source-to-doc traceability**: Closeout is credible only when implementation, tests, docs, API notes, and security records are reconciled. *** ## 9. Testing Strategy ### Unit Tests * Run existing unit and component suites with `bun run test`. * Add or adjust narrow docs/reference tests only if the registry or Markdown link behavior changes. ### Integration Tests * Run `bun run typecheck` and `bun run typecheck:scripts`. * Run static Brief export validation and private-artifact checks. * Run payload budget verification against bounded Trend Finder output. ### Manual Testing * Open or inspect Engine Replay Reference mode behavior for updated manuals. * Review the coverage matrix proving `alpha-radar.md` can be deleted. * Review changed docs for AI OS / Trend Finder boundary accuracy. ### Edge Cases * Legacy payloads without Phase 27 fields remain documented as additive defaults. * Deferred source candidates remain future work, not implemented features. * Validation failures from unrelated existing files are separated from session-owned release blockers. *** ## 10. Dependencies ### External Libraries * None added. ### Other Sessions * **Depends on**: Phase 27 Sessions 01-11. * **Depended by**: Phase 27 validation, update PRD, phase transition audit, and any future source-expansion or SQLite observation-store phase. *** ## 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/phase27-session12-documentation-validation-and-release/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.