> 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/implementation-notes.md). # Implementation Notes **Session ID**: `phase24-session07-static-brief-export` **Started**: 2026-06-08 04:22 **Last Updated**: 2026-06-08 05:33 *** ## Session Progress | Metric | Value | | ------------------- | --------- | | Tasks Completed | 25 / 25 | | Estimated Remaining | 0 minutes | | Blockers | 0 | *** ## Task Log ### 2026-06-08 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Tools available through the local Bun project toolchain * [x] Directory structure ready *** ### Task T001 - Verify Phase 24 prerequisites and existing Trend Finder contracts **Started**: 2026-06-08 04:21 **Completed**: 2026-06-08 04:22 **Duration**: 1 minute **Notes**: * Confirmed Session 03 asset hardening validation passed, including manifest containment, local bridge rules, schema compatibility, and asset fallback states. * Confirmed Session 06 Workbench validation passed and documented that triage state is browser-local only and must not be exported. * Reviewed the Brief tab path, Trend Finder schema validation, evidence asset helpers, and generated-data privacy scanner. **Files Changed**: * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - initialized session progress log * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T001 complete **BQC Fixes**: * N/A - setup verification only. *** ### Task T002 - Confirm live-data extraction and generated export strategy **Started**: 2026-06-08 04:22 **Completed**: 2026-06-08 04:23 **Duration**: 1 minute **Notes**: * Confirmed committed fallback data lives at `src/data/live-data.example.json`; generated local data remains `src/data/live-data.json`. * Confirmed `.cache/` is ignored and is appropriate for the default `.cache/extensions/trend-finder/static-brief/` root. * Confirmed package scripts use `bun run scripts/...` and e2e fixtures already provide localStorage and populated live-data helpers. **Files Changed**: * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T002 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T002 complete **BQC Fixes**: * N/A - setup verification only. *** ### Task T003 - Review Outlier Lab static export references and docs boundary **Started**: 2026-06-08 04:23 **Completed**: 2026-06-08 04:24 **Duration**: 1 minute **Notes**: * Reviewed Outlier Lab static report generation, setup page, and Vercel cache-header guidance as references only. * Confirmed AI OS docs currently say generated HTML report output is not implemented and that public deployment, generated artifact commits, and default hosting must not be copied as defaults. * Set implementation direction to a script-only local report with documentation for optional operator hosting only. **Files Changed**: * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T003 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T003 complete **BQC Fixes**: * N/A - setup verification only. *** ### Task T004 - Create static Brief export contract and safe report validation **Started**: 2026-06-08 04:24 **Completed**: 2026-06-08 04:31 **Duration**: 7 minutes **Notes**: * Added the static Brief report contract, bounded limits, warning codes, export result summaries, and Zod-backed report validation. * Added private-field and private-string scanning that runs on raw Trend Finder input, projected reports, rendered HTML, and manifest data. * Added safe report projection scaffolding for source health, ranked topics, public evidence, predictions/retros, spend, enrichment, assets, and cache-header guidance. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - created export contract, schemas, privacy scanner, projection scaffolding, and result types * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T004 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T004 complete **BQC Fixes**: * Trust boundary enforcement: raw input and projected output now fail closed for private field names, token-shaped strings, local home paths, and private Trend Finder cache paths. * Error information boundaries: export errors use stable codes and safe messages without emitting private paths from scanned payloads. *** ### Task T005 - Create static Brief renderer primitives **Started**: 2026-06-08 04:24 **Completed**: 2026-06-08 04:32 **Duration**: 8 minutes **Notes**: * Added deterministic standalone HTML rendering with text escaping, attribute escaping, safe inline JSON serialization, URL filtering, responsive CSS, landmarks, and empty states. * Added browser-only copy-link behavior with no remote scripts or persistence. * Kept report interactivity transient so reloads reset copy button state. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-renderer.ts` - created renderer, escaping helpers, safe URL filter, inline JSON serializer, styles, and copy-link script * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T005 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T005 complete **BQC Fixes**: * Trust boundary enforcement: renderer filters outbound evidence links to public HTTP(S) URLs and escapes every interpolated text/attribute value. * Accessibility and platform compliance: report sections use semantic headings, details/summary controls, buttons, and aria-labelled metadata. * State freshness on re-entry: copy button state is reset during page load and no localStorage state is used. *** ### Task T006 - Implement live-data loading and Trend Finder extraction **Started**: 2026-06-08 04:31 **Completed**: 2026-06-08 04:33 **Duration**: 2 minutes **Notes**: * Added JSON loading for the generated live-data input with explicit missing, empty, unreadable, and invalid JSON errors. * Extracted `extensions.items["trend-finder"].data` and validated it through `validateTrendFinderData`. * Mapped schema issues into stable export errors before projection or writes can run. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - added live-data loader, Trend Finder branch extraction, and error mapping * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T006 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T006 complete **BQC Fixes**: * Failure path completeness: malformed input now returns explicit coded failures instead of falling back to empty reports. * Trust boundary enforcement: Trend Finder data is schema-validated before report projection. *** ### Task T007 - Implement output root resolution and atomic writes **Started**: 2026-06-08 04:31 **Completed**: 2026-06-08 04:33 **Duration**: 2 minutes **Notes**: * Added default output root resolution for `.cache/extensions/trend-finder/static-brief/`. * Rejected empty paths, traversal segments, project-root targets, and source/docs/git/spec/dependency roots. * Added temporary directory writes and backup/restore promotion so validation failures do not replace a previous export. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - added output path validation and atomic output writer * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T007 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T007 complete **BQC Fixes**: * Resource cleanup: temporary output and backup directories are removed or restored on failed writes. * Failure path completeness: unsafe output paths fail before any final output is touched. *** ### Task T008 - Implement safe report projection **Started**: 2026-06-08 04:31 **Completed**: 2026-06-08 04:33 **Duration**: 2 minutes **Notes**: * Projected validated Trend Finder data into bounded static report rows for run metadata, source health, topics, score/actionability labels, public evidence links, spend, enrichment, assets, predictions, and retros. * Preserved deterministic ranking by reusing existing Trend Finder view-model ordering and caps. * Filtered evidence URLs to public HTTP(S) links and emitted explicit empty/fallback labels. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - added bounded static report projection * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T008 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T008 complete **BQC Fixes**: * Contract alignment: projection output is parsed by `StaticBriefReportSchema` before rendering. * Failure path completeness: missing optional sections render explicit empty state labels. *** ### Task T009 - Implement static export asset policy **Started**: 2026-06-08 04:31 **Completed**: 2026-06-08 04:33 **Duration**: 2 minutes **Notes**: * Added default asset manifest lookup under `.cache/extensions/trend-finder/assets`. * Copied only validated available manifest assets into the report-local `assets/` directory. * Rendered fallback labels for unavailable, unsupported, blocked, failed, missing, uncopied, or manifest-missing assets. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - added asset manifest lookup, validation, copy planning, and fallback labeling * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T009 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T009 complete **BQC Fixes**: * Trust boundary enforcement: asset IDs and manifest paths are validated through existing asset hardening helpers. * Failure path completeness: missing or unsupported assets fall back to labels without blocking the export. *** ### Task T010 - Implement final report privacy scanner **Started**: 2026-06-08 04:31 **Completed**: 2026-06-08 04:33 **Duration**: 2 minutes **Notes**: * Added final privacy assertions for projected report JSON, rendered HTML, and manifest data. * Rejected token-shaped strings, local home paths, private Trend Finder cache paths, prompts, provider responses, raw logs, raw source dumps, Actor/Dataset internals, account auth, credentials, and local triage/visibility fields. * Verified the script typecheck passes after the foundation implementation. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - added recursive privacy scanner and final output assertions * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T010 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T010 complete **BQC Fixes**: * Error information boundaries: privacy failures emit issue locations and stable private-category names without echoing secret values. * Contract alignment: rendered HTML cannot be written unless report and manifest privacy scans pass. *** ### Task T011 - Create static Brief export CLI **Started**: 2026-06-08 04:34 **Completed**: 2026-06-08 04:37 **Duration**: 3 minutes **Notes**: * Added CLI parsing for `--input`, `--output`, `--dry-run`, `--json`, and `--help`. * Added human and JSON summaries, redacted error output, stable usage/runtime exit codes, env loading, and SIGINT abort propagation. * Verified script typecheck passes after the CLI entrypoint. **Files Changed**: * `scripts/trend-finder-export-brief.ts` - created CLI entrypoint and reusable parser/runner helpers * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T011 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T011 complete **BQC Fixes**: * Failure path completeness: CLI usage and runtime errors produce explicit exit codes and safe messages. * Error information boundaries: CLI error output redacts home paths and token-shaped secret prefixes. *** ### Task T012 - Add package script for opt-in export **Started**: 2026-06-08 04:36 **Completed**: 2026-06-08 04:37 **Duration**: 1 minute **Notes**: * Added `trend-finder:export-brief` as an explicit opt-in package script. * Left default build, dev, aggregate, scheduler, and deployment workflows unchanged. **Files Changed**: * `package.json` - added `trend-finder:export-brief` * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T012 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T012 complete **BQC Fixes**: * N/A - package script registration only. *** ### Task T013 - Render standalone report shell and sections **Started**: 2026-06-08 04:24 **Completed**: 2026-06-08 04:39 **Duration**: 15 minutes **Notes**: * Added standalone report HTML with metadata, summary metrics, top opportunities, public evidence, source health, prediction/retro rows, spend, enrichment, assets, warnings, and explicit empty states. * Kept the renderer dependency-free and usable outside the running AI OS app. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-renderer.ts` - added full report shell and static report sections * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T013 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T013 complete **BQC Fixes**: * Accessibility and platform compliance: sections use headings and details/summary controls with native keyboard behavior. * Failure path completeness: missing topics, evidence, sources, predictions, retros, and warnings render explicit empty labels. *** ### Task T014 - Add browser-only report interactivity **Started**: 2026-06-08 04:24 **Completed**: 2026-06-08 04:39 **Duration**: 15 minutes **Notes**: * Added native expandable report sections for evidence, sources, predictions/retros, and operational summaries. * Added copy-link buttons for safe public evidence links where clipboard support exists. * Reset transient button state on page load and avoided localStorage or external dependencies. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-renderer.ts` - added details/summary expansion and copy-link script * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T014 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T014 complete **BQC Fixes**: * State freshness on re-entry: transient copy state is reset on reload. * Failure path completeness: unsupported clipboard paths show an explicit unavailable state. *** ### Task T015 - Write export metadata and manifest summary **Started**: 2026-06-08 04:31 **Completed**: 2026-06-08 04:39 **Duration**: 8 minutes **Notes**: * Added `manifest.json` generation with schema version, generated timestamp, source live-data label, run ID, counts, skipped asset counts, privacy warning placeholder, and cache-header guidance. * Kept manifest values browser-safe and privacy-scanned before final write. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - added manifest generation and manifest privacy validation * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T015 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T015 complete **BQC Fixes**: * Contract alignment: manifest is derived from the validated report contract and checked before write. * Error information boundaries: manifest uses a safe live-data label rather than absolute local paths. *** ### Task T016 - Enforce unsafe asset fallback and path-escape failures **Started**: 2026-06-08 04:31 **Completed**: 2026-06-08 04:39 **Duration**: 8 minutes **Notes**: * Allowed unsupported, blocked, failed, missing, and manifest-missing assets to render safe fallback labels. * Failed closed for manifest references that violate path containment or relative-path rules. * Copied only validated report-local assets and never emitted bridge URLs or private asset source paths. **Files Changed**: * `scripts/extensions/trend-finder/static-brief-export.ts` - added asset fallback and fail-closed handling * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T016 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T016 complete **BQC Fixes**: * Trust boundary enforcement: asset path escapes are treated as fatal export errors. * Failure path completeness: safe fallback labels keep the static report usable when optional assets are unavailable. *** ### Task T017 - Add static export fixture coverage **Started**: 2026-06-08 04:40 **Completed**: 2026-06-08 04:43 **Duration**: 3 minutes **Notes**: * Added named static Brief export fixture data with exportable topics, source health, spend, enrichment, asset states, predictions, and retros. * Added unsafe raw payload variants for local triage and unsafe asset privacy tests. * Added an e2e live-data builder for static Brief browser smoke tests. * Verified app and script typechecks pass after fixture changes. **Files Changed**: * `src/extensions/trend-finder/fixtures.ts` - added static export and unsafe payload fixtures * `tests/e2e/fixtures/live-data.ts` - added static Brief live-data builder * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T017 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T017 complete **BQC Fixes**: * Contract alignment: fixture exports typecheck against `TrendFinderData`. *** ### Task T018 - Update extension docs README for static Brief export **Started**: 2026-06-08 04:43 **Completed**: 2026-06-08 04:47 **Duration**: 4 minutes **Notes**: * Replaced the stale generated-HTML deferred language with the implemented local opt-in static Brief export. * Documented the generated output root, exclusions, and non-default hosting/commit boundary. **Files Changed**: * `docs/extensions/README_docs-extensions.md` - updated current Trend Finder behavior and deferred/default boundaries * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T018 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T018 complete **BQC Fixes**: * N/A - documentation update. *** ### Task T019 - Update pipeline docs for static Brief export **Started**: 2026-06-08 04:43 **Completed**: 2026-06-08 04:47 **Duration**: 4 minutes **Notes**: * Documented the export command, dry-run and output examples, generated output root, validation failures, privacy exclusions, asset fallback behavior, and optional cache-header guidance. * Added static export files to the Trend Finder implementation map. **Files Changed**: * `docs/extensions/trend-finder-pipeline.md` - added static Brief export section and implementation map rows * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T019 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T019 complete **BQC Fixes**: * N/A - documentation update. *** ### Task T020 - Update UI surface docs for Brief export behavior **Started**: 2026-06-08 04:43 **Completed**: 2026-06-08 04:47 **Duration**: 4 minutes **Notes**: * Documented the relationship between the dashboard Brief tab and the script-side static Brief export. * Listed report sections, local triage and visibility exclusions, safe evidence links, standalone report interactions, and generated output limitations. **Files Changed**: * `docs/extensions/trend-finder-ui-surfaces.md` - added static Brief export behavior and exclusions * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T020 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T020 complete **BQC Fixes**: * N/A - documentation update. *** ### Task T021 - Update runtime and provenance docs for static export **Started**: 2026-06-08 04:43 **Completed**: 2026-06-08 04:47 **Duration**: 4 minutes **Notes**: * Documented static export provenance labels, privacy scans, generated artifact boundaries, skipped/uncopied asset behavior, and raw runtime/private cache exclusions. **Files Changed**: * `docs/extensions/trend-finder-runtime-and-provenance.md` - added static export provenance and asset boundary notes * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T021 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T021 complete **BQC Fixes**: * N/A - documentation update. *** ### Task T022 - Write static export unit tests **Started**: 2026-06-08 04:47 **Completed**: 2026-06-08 04:52 **Duration**: 5 minutes **Notes**: * Added tests for live-data branch extraction, invalid payloads, dry-run behavior, output containment, atomic write preservation, asset copying, asset fallback, private-data rejection, and CLI parser/output behavior. * Focused export and renderer unit tests passed: 2 files, 10 tests. **Files Changed**: * `scripts/extensions/trend-finder/__tests__/static-brief-export.test.ts` - added export and CLI unit coverage * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T022 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T022 complete **BQC Fixes**: * Contract alignment: tests verify schema-valid fixture projection and invalid input rejection. * Failure path completeness: tests verify dry-run no-write and prior export preservation on validation failure. *** ### Task T023 - Write renderer unit tests **Started**: 2026-06-08 04:48 **Completed**: 2026-06-08 04:52 **Duration**: 4 minutes **Notes**: * Added tests for HTML escaping, attribute escaping, inline JSON escaping, public URL filtering, row caps, semantic landmarks, empty states, and no remote script dependencies. * Focused export and renderer unit tests passed: 2 files, 10 tests. **Files Changed**: * `scripts/extensions/trend-finder/__tests__/static-brief-renderer.test.ts` - added renderer unit coverage * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T023 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T023 complete **BQC Fixes**: * Trust boundary enforcement: tests verify escaping and URL filtering behavior. * Accessibility and platform compliance: tests verify semantic report landmarks and native sections exist. *** ### Task T024 - Write static report browser smoke test **Started**: 2026-06-08 04:49 **Completed**: 2026-06-08 04:52 **Duration**: 3 minutes **Notes**: * Added a Playwright smoke that exports fixture live data, opens the generated `index.html`, verifies report sections, checks public evidence links and copy buttons, checks desktop/mobile overflow, and asserts private strings are absent. * Fixed a Vite config runtime import issue by changing `src/lib/async-trend-finder-run.ts` to use a relative scheduler-status import. * Installed the missing Playwright Chromium binary for this environment. * Browser smoke passed: 1 test. **Files Changed**: * `tests/e2e/trend-finder-static-brief.spec.ts` - added static report browser smoke * `src/lib/async-trend-finder-run.ts` - changed a Vite-config-loaded import from TS alias to relative path * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged T024 * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T024 complete **BQC Fixes**: * Accessibility and platform compliance: browser smoke verifies generated report headings and controls render in Chromium. * Failure path completeness: browser smoke verifies private strings do not appear in the generated static HTML. *** ### Task T025 - Run final validation and diff review **Started**: 2026-06-08 04:52 **Completed**: 2026-06-08 04:55 **Duration**: 3 minutes **Notes**: * `bun run typecheck:scripts` passed. * `bun run typecheck` passed. * Focused static export, renderer, evidence asset, and Trend Finder schema tests passed: 4 files, 92 tests. * `bunx playwright test tests/e2e/trend-finder-static-brief.spec.ts` passed: 1 Chromium test opening the generated report through a direct `file://` URL. * `bun run trend-finder:export-brief -- --dry-run --json` passed against the default live-data path. * `bun run trend-finder:export-brief -- --json` wrote the generated report to `.cache/extensions/trend-finder/static-brief/`. * Targeted ESLint passed for all session-touched code files. * `bunx prettier --check` passed for session-touched docs, code, tests, and spec bookkeeping files. * ASCII/LF validation passed for 16 session-touched deliverables. * `git diff --check` passed. * Full `bun run lint` initially failed on broader Trend Finder formatting and lint drift outside the new static export files; those repo-wide lint/format failures were fixed during validate rerun. * Full validation rerun passed: `bun run typecheck`, `bun run typecheck:scripts`, `bun run lint`, `bun run format:check`, `bun run test` (241 files, 3091 tests), static export dry-run/write commands, the static Brief Playwright smoke, changed-file ASCII/LF validation, and `git diff --check`. * Validation-time behavioral fix: memoized parsed Trend Finder data in `SourcesView` to prevent source setup and scheduler status effects from looping on fresh parsed object identities. * Validation-time test fix: updated the dashboard evidence-metrics assertion to allow source-local metric chips while confirming raw count chips stay absent when evidence has no raw public counts. **Files Changed**: * `.spec_system/specs/phase24-session07-static-brief-export/implementation-notes.md` - logged final validation outcomes * `.spec_system/specs/phase24-session07-static-brief-export/tasks.md` - marked T025 and completion checklist complete **BQC Fixes**: * N/A - validation task; prior task logs captured code-specific BQC checks. *** --- # 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/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.