> 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/implementation-notes.md). # Implementation Notes **Session ID**: `phase29-session13-static-brief-archival-and-richness` **Started**: 2026-06-21 03:09 **Last Updated**: 2026-06-21 05:04 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 20 / 20 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ### Task T020 - Run focused validation commands **Started**: 2026-06-21 04:52 **Completed**: 2026-06-21 05:04 **Duration**: 12 minutes **Notes**: * Ran Prettier on all session-touched code and docs files. * Ran focused Vitest suites for static Brief archive, export, renderer, and QA: 4 files passed, 28 tests passed. * Ran `bun run typecheck:scripts`: passed. * Ran `bun run test:e2e -- tests/e2e/trend-finder-static-brief.spec.ts`: passed after fixing latest-pointer e2e timing and strict locator assertions. * Ran `bun run runtime:check-private`: passed. * Ran Trend Finder payload budget check with `--threshold-kb=1024`: passed, `extensions.items["trend-finder"].data` measured 457150 bytes. * Ran ASCII and CRLF checks across session files: passed. * Ran fixture-backed manual CLI smoke for dry-run JSON, default write, and archive write: passed. **Files Changed**: * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T020 and completion checklist complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded validation outcomes. **BQC Fixes**: * Failure path completeness: Validation caught and fixed Playwright latest-pointer timing and strict locator issues (`tests/e2e/trend-finder-static-brief.spec.ts`). *** ## Validation Summary | Command | Result | | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | | `bunx prettier --write ` | Pass | | `bun run test -- scripts/extensions/trend-finder/__tests__/static-brief-archive.test.ts scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts scripts/extensions/trend-finder/__tests__/static-brief-qa.test.ts` | Pass - 4 files, 28 tests | | `bun run typecheck:scripts` | Pass | | `bun run test:e2e -- tests/e2e/trend-finder-static-brief.spec.ts` | Pass - 1 test | | `bun run runtime:check-private` | Pass | | `bun run scripts/extensions/trend-finder/measure-payload-size.ts src/data/live-data.json --threshold-kb=1024 --json` | Pass - Trend Finder data payload 457150 bytes | | ASCII and CRLF checks for session-touched files | Pass | | Fixture-backed CLI smoke: dry-run JSON, default write, archive write | Pass | ### Residual Validation Note `bun run budget:check` was also run after `bun run clean && bun run build`. It failed on an existing total client JS gzip budget overage: 1216 KB actual against a 1200 KB budget. This session changed script, docs, tests, and spec files only; the Trend Finder payload budget check passed. *** ### Task T019 - Add Playwright archive static Brief coverage **Started**: 2026-06-21 04:46 **Completed**: 2026-06-21 04:52 **Duration**: 6 minutes **Notes**: * Extended static Brief e2e to export archive mode and open the report through `latest.html`. * Added archive run metadata, richer signal text, public link, privacy, no-media, desktop overflow, and mobile overflow checks. **Files Changed**: * `tests/e2e/trend-finder-static-brief.spec.ts` - Added archive latest pointer e2e coverage. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T019 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded e2e coverage. **BQC Fixes**: * Accessibility and platform compliance: E2E opens the archive through visible pointer navigation fallback and checks responsive overflow (`tests/e2e/trend-finder-static-brief.spec.ts`). *** ### Task T018 - Add renderer and QA rich-field tests **Started**: 2026-06-21 04:39 **Completed**: 2026-06-21 04:46 **Duration**: 7 minutes **Notes**: * Added renderer assertions for topic signal context, attention, reception, corroboration, and evidence topic-context labels. * Added QA coverage for actual media/embed tags in rendered HTML. * Added QA coverage for unsafe latest pointer links and private strings in rendered latest pointer HTML. **Files Changed**: * `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` - Added richer static Brief rendering assertions. * `scripts/extensions/trend-finder/__tests__/static-brief-qa.test.ts` - Added media, archive pointer, and latest pointer privacy QA tests. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T018 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded renderer and QA tests. **BQC Fixes**: * Failure path completeness: QA tests prove media embeds and unsafe/private latest pointer output become blocking failures (`scripts/extensions/trend-finder/__tests__/static-brief-qa.test.ts`). * Contract alignment: Renderer tests prove the new projection fields are included in bounded static Brief HTML (`scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts`). *** ### Task T017 - Add archive helper and exporter tests **Started**: 2026-06-21 04:28 **Completed**: 2026-06-21 04:39 **Duration**: 11 minutes **Notes**: * Added unit tests for archive run discovery, invalid-name filtering, next-run planning, latest pointer rendering, unsafe latest href rejection, and contained atomic write plans. * Added exporter tests for archive run writes, `latest.html` updates, archive manifest metadata, default manifest compatibility, CLI archive JSON output, and QA failure preserving the previous archive. **Files Changed**: * `scripts/extensions/trend-finder/__tests__/static-brief-archive.test.ts` - New archive helper tests. * `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts` - Added archive exporter and CLI coverage. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T017 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded archive tests. **BQC Fixes**: * Failure path completeness: Tests assert failed archive QA preserves the prior latest pointer and does not create the next run (`scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`). * Contract alignment: Tests assert default manifests remain archive-free while archive manifests include relative archive metadata (`scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts`). *** ### Task T016 - Document archive CLI flag and output states **Started**: 2026-06-21 04:25 **Completed**: 2026-06-21 04:28 **Duration**: 3 minutes **Notes**: * Added `--archive` command example. * Documented default output layout and archive output layout. * Documented archive pass/fail states, side effects, QA failures, unsafe latest pointer failures, media-embed failures, and local-only generated report guidance. **Files Changed**: * `docs/commands.md` - Updated `trend-finder:export-brief` command reference. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T016 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded command docs update. *** ### Task T015 - Document static Brief archive behavior **Started**: 2026-06-21 04:20 **Completed**: 2026-06-21 04:25 **Duration**: 5 minutes **Notes**: * Documented default non-archive output compatibility. * Documented archive root layout, numbered run directories, `latest.html`, relative links, failure safety, and archive metadata. * Documented the privacy and no-media-embed boundary for richer static Brief output. **Files Changed**: * `docs/extensions/trend-finder-pipeline.md` - Added archive mode and richer static Brief documentation. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T015 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded documentation update. *** ### Task T014 - Complete CLI archive mode output **Started**: 2026-06-21 04:17 **Completed**: 2026-06-21 04:20 **Duration**: 3 minutes **Notes**: * Added archive run, latest pointer, and source run lines to human CLI output when archive mode is enabled. * Confirmed JSON output uses the export summary, which now includes archive fields. * Preserved existing static Brief error redaction and exporter-level duplicate output lock. **Files Changed**: * `scripts/trend-finder-export-brief.ts` - Added archive-aware human output. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T014 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded CLI output work. **BQC Fixes**: * Error information boundaries: CLI archive paths still pass through existing redaction for unexpected errors and static Brief export errors (`scripts/trend-finder-export-brief.ts`). * Contract alignment: Human and JSON output now both expose archive state when archive mode is used (`scripts/trend-finder-export-brief.ts`). *** ### Task T013 - Enforce archive, privacy, and media QA failures **Started**: 2026-06-21 04:12 **Completed**: 2026-06-21 04:17 **Duration**: 5 minutes **Notes**: * Tightened archive QA so manifest run number, source run ID, QA status, archived index path, and latest pointer href must align with report metadata. * Kept private string checks active across report, rendered HTML, manifest, and rendered latest pointer HTML. * Added rendered media/embed detection to fail before promotion. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-qa.ts` - Added archive metadata alignment and fail-closed latest/media checks. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T013 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded QA enforcement work. **BQC Fixes**: * Failure path completeness: Archive metadata, latest pointer, private-string, and media-embed failures now surface as blocking QA issues before promotion (`scripts/extensions/trend-finder/static-brief-qa.ts`). * Error information boundaries: QA issues describe stable metadata mismatches and unsafe path classes without exposing private file contents (`scripts/extensions/trend-finder/static-brief-qa.ts`). *** ### Task T012 - Render denser topic and evidence sections **Started**: 2026-06-21 04:07 **Completed**: 2026-06-21 04:12 **Duration**: 5 minutes **Notes**: * Rendered topic signal chips for attention, reception, and corroboration inside top opportunity rows. * Rendered evidence topic-context labels near public evidence links. * Used text-only elements, native links/buttons/details, labels, and titles; no image, iframe, audio, video, embed, object, or remote script output was added. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-renderer.ts` - Added signal chip and evidence context rendering plus responsive styles. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T012 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded renderer enrichment work. **BQC Fixes**: * Accessibility and platform compliance: Rich signal chips expose aria labels and details/links/buttons remain native keyboard-accessible controls (`scripts/extensions/trend-finder/static-brief-renderer.ts`). * Error information boundaries: Rendering continues to escape all projected strings and avoids raw payload/media branches (`scripts/extensions/trend-finder/static-brief-renderer.ts`). *** ### Task T011 - Enrich static Brief projection **Started**: 2026-06-21 04:00 **Completed**: 2026-06-21 04:07 **Duration**: 7 minutes **Notes**: * Projected topic signal chips from existing attention pattern, aggregate reception, and corroboration view models. * Added bounded topic-context labels to evidence rows based on already-ranked topic/evidence relationships. * Preserved existing polarity grid and evidence-rationale projections as the authoritative report fields for those details. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - Added signal chip and evidence topic-context projection. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T011 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded projection enrichment work. **BQC Fixes**: * Contract alignment: Richer fields are built from existing normalized view-model helpers, preserving enum label/tone handling instead of duplicating raw enum switches (`scripts/extensions/trend-finder/static-brief-export.ts`). * Trust boundary enforcement: Evidence context labels are bounded, deduplicated, and derived from already-published topic/evidence IDs (`scripts/extensions/trend-finder/static-brief-export.ts`). *** ### Task T010 - Add archive manifest and JSON summary fields **Started**: 2026-06-21 03:58 **Completed**: 2026-06-21 04:00 **Duration**: 2 minutes **Notes**: * Added manifest archive metadata for run number, run directory, relative archived index path, latest pointer path, latest pointer href, source run ID, and QA status. * Added export summary fields for archive enablement, run number, run directory, archived index path, latest pointer path, and source run ID. * Kept default JSON summaries explicit with `archiveEnabled: false` and nullable archive paths. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - Added archive manifest and export summary fields. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T010 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded manifest and summary metadata work. **BQC Fixes**: * Contract alignment: Archive manifest metadata uses relative public report paths while JSON summary paths identify the concrete local files written by the command (`scripts/extensions/trend-finder/static-brief-export.ts`). *** ### Task T009 - Wire archive mode into export write path **Started**: 2026-06-21 03:44 **Completed**: 2026-06-21 03:58 **Duration**: 14 minutes **Notes**: * Planned archive runs inside the existing output-directory in-flight lock. * Rendered archive metadata into the report before manifest candidate and QA construction. * Added archive promotion that writes the run directory first, then atomically promotes `latest.html`; if pointer promotion fails, the new run directory is removed and any prior run backup is restored. * Preserved the default non-archive write path and default `index.html`/`manifest.json` summary paths. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - Added archive planning, metadata application, archive promotion, latest pointer privacy checks, and default/archived summary branching. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T009 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded archive write wiring. **BQC Fixes**: * Duplicate action prevention: Archive planning and writes reuse the existing active output directory lock (`scripts/extensions/trend-finder/static-brief-export.ts`). * Failure path completeness: Failed QA or privacy scans occur before any archive promotion; failed latest pointer promotion removes the new run directory and restores prior run backup if present (`scripts/extensions/trend-finder/static-brief-export.ts`). * Resource cleanup: Temp run directories, temp latest pointer files, and backup directories are cleaned or restored in `finally` paths (`scripts/extensions/trend-finder/static-brief-export.ts`). *** ### Task T008 - Implement archive numbering and latest pointer generation **Started**: 2026-06-21 03:41 **Completed**: 2026-06-21 03:44 **Duration**: 3 minutes **Notes**: * Verified helper implementation for `run-0001` style parsing, scan limits, ignored invalid entries, and deterministic run sorting. * Confirmed latest pointer hrefs are normalized, relative, non-traversing, and target archived `index.html` files. * Confirmed pointer rendering contains no iframe, image, audio, video, embed, object, or remote script output. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-archive.ts` - Confirmed implementation covers run discovery and latest pointer generation. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T008 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded helper implementation completion. **BQC Fixes**: * State freshness on re-entry: Next-run planning scans the current archive directory at execution time rather than reusing cached state (`scripts/extensions/trend-finder/static-brief-archive.ts`). * Error information boundaries: Archive errors report stable codes and bounded issue strings without absolute source payload details (`scripts/extensions/trend-finder/static-brief-archive.ts`). *** ### Task T007 - Add archive and media QA contract checks **Started**: 2026-06-21 03:34 **Completed**: 2026-06-21 03:41 **Duration**: 7 minutes **Notes**: * Added QA issue codes for missing archive metadata, unsafe latest pointer links, and media embeds. * Added archive QA context so archive runs can validate the rendered `latest.html` pointer before promotion. * Added fail-closed media/embed detection for rendered static Brief HTML and latest pointer HTML. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-qa.ts` - Added archive metadata, latest pointer, and media/embed QA checks. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T007 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded QA contract work. **BQC Fixes**: * Trust boundary enforcement: Latest pointer hrefs are validated through the archive helper before QA passes (`scripts/extensions/trend-finder/static-brief-qa.ts`). * Failure path completeness: Missing archive metadata and rendered media/embed tags now produce explicit blocking QA issues (`scripts/extensions/trend-finder/static-brief-qa.ts`). *** ### Task T006 - Define renderer archive and rich-context contract **Started**: 2026-06-21 03:29 **Completed**: 2026-06-21 03:34 **Duration**: 5 minutes **Notes**: * Added defaulted `archive` metadata to the static Brief report schema. * Added defaulted topic signal chips and evidence topic-context labels for later projection/rendering work. * Added header rendering for archive run labels when archive metadata is enabled. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - Added archive, topic signal, and evidence context schema fields. * `scripts/extensions/trend-finder/static-brief-renderer.ts` - Added archive metadata tags to the report header. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T006 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded renderer contract work. **BQC Fixes**: * Contract alignment: New report fields are schema-defaulted so older/default projections remain valid while archive reports can identify their run (`scripts/extensions/trend-finder/static-brief-export.ts`). * Accessibility and platform compliance: Archive metadata is rendered through existing text tags inside the report metadata region, with no iframe, image, audio, or video output (`scripts/extensions/trend-finder/static-brief-renderer.ts`). *** ### Task T005 - Extend CLI option parsing and usage text **Started**: 2026-06-21 03:26 **Completed**: 2026-06-21 03:29 **Duration**: 3 minutes **Notes**: * Added `--archive` to CLI option parsing and usage text. * Passed the parsed archive option to `runStaticBriefExport`. * Kept duplicate-trigger prevention centralized in the exporter output-directory lock that the CLI already uses. **Files Changed**: * `scripts/trend-finder-export-brief.ts` - Added archive CLI flag parsing and option forwarding. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T005 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded CLI contract work. **BQC Fixes**: * Duplicate action prevention: CLI archive mode flows through the existing `activeStaticBriefOutputDirs` lock instead of adding a second write path (`scripts/trend-finder-export-brief.ts`). *** ### Task T004 - Extend export option, summary, and manifest types **Started**: 2026-06-21 03:22 **Completed**: 2026-06-21 03:26 **Duration**: 4 minutes **Notes**: * Added an opt-in `archive` boolean to `StaticBriefExportOptions` and parse it through a Zod boolean schema. * Added typed archive manifest metadata for run number, run directory, relative archived index, latest pointer, source run ID, and QA status. * Added nullable archive fields to the export summary while preserving default `index.html` and `manifest.json` path calculation. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - Extended export and manifest contracts for archive metadata. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T004 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded export contract work. **BQC Fixes**: * Contract alignment: Default summaries now explicitly expose `archiveEnabled: false` and nullable archive paths so callers do not infer archival from existing default paths (`scripts/extensions/trend-finder/static-brief-export.ts`). *** ### Task T003 - Create static Brief archive helper contract **Started**: 2026-06-21 03:14 **Completed**: 2026-06-21 03:22 **Duration**: 8 minutes **Notes**: * Added a dedicated archive helper for validated `run-0001` style directory discovery, safe latest pointer hrefs, and deterministic next-run planning. * Added atomic write plan paths for temp run directories, backup run directories, and temp latest pointer writes under the archive root. * Added a media-free `latest.html` pointer renderer using only a safe relative archive link. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-archive.ts` - New helper contract and path/pointer planning functions. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T003 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded helper contract work. **BQC Fixes**: * Trust boundary enforcement: Archive roots, run numbers, operation IDs, and latest pointer hrefs are validated before paths are returned (`scripts/extensions/trend-finder/static-brief-archive.ts`). * Failure path completeness: Archive scan failures use explicit typed archive errors with issue details (`scripts/extensions/trend-finder/static-brief-archive.ts`). *** ### Task T002 - Inspect static Brief defaults before editing **Started**: 2026-06-21 03:10 **Completed**: 2026-06-21 03:14 **Duration**: 4 minutes **Notes**: * Read the static Brief exporter, renderer, QA, CLI, focused tests, Playwright e2e, docs, and package command wiring. * Confirmed default export currently resolves one output root and promotes `index.html`, `manifest.json`, and copied `assets/` after QA and privacy scans. * Confirmed existing renderer already escapes content, stores bounded inline JSON, avoids remote scripts, and uses report-local asset links instead of media embeds. **Files Changed**: * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T002 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded baseline behavior. *** ### Task T001 - Verify analyzer state and session scope **Started**: 2026-06-21 03:09 **Completed**: 2026-06-21 03:10 **Duration**: 1 minute **Notes**: * Ran the spec analyzer and confirmed current session `phase29-session13-static-brief-archival-and-richness`. * Confirmed Phase 29 is in progress and prerequisite Phase 29 Sessions 02, 03, and 05 are completed in state. * Read the Session 13 PRD stub and verified scope matches optional static Brief archival and richer media-free Brief output. **Files Changed**: * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/tasks.md` - Marked T001 complete. * `.spec_system/specs/phase29-session13-static-brief-archival-and-richness/implementation-notes.md` - Recorded setup verification. *** ## Task Log ### 2026-06-21 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available * [x] Directory structure ready *** --- # 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/implementation-notes.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.