> 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-session04-source-setup-target-configuration/implementation-notes.md). # Implementation Notes **Session ID**: `phase24-session04-source-setup-target-configuration` **Started**: 2026-06-08 00:59 **Last Updated**: 2026-06-08 02:38 *** ## Session Progress | Metric | Value | | ------------------- | ------- | | Tasks Completed | 25 / 25 | | Estimated Remaining | 0 hours | | Blockers | 0 | *** ### Task T025 - Run final verification **Started**: 2026-06-08 02:34 **Completed**: 2026-06-08 02:38 **Duration**: 4 minutes **Notes**: * Focused helper tests passed: `bun run vitest run scripts/extensions/trend-finder/sources/__tests__/source-setup.test.ts`. * Focused bridge tests passed: `bun run vitest run scripts/lib/__tests__/trend-finder-source-setup-bridge.test.ts`. * Focused browser tests passed: `bun run vitest run src/extensions/trend-finder/components/__tests__/source-setup-panel.test.tsx`. * App typecheck passed: `bun run typecheck`. * Script typecheck passed: `bun run typecheck:scripts`. * Documentation formatting check passed: `bun run prettier --check docs/extensions/trend-finder-sources.md docs/sources/apify-source-onboarding.md docs/apify.md`. * ASCII validation passed for touched files. * Git whitespace check passed: `git diff --check`. **Files Changed**: * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T025 and the completion checklist complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged final verification **BQC Fixes**: * Contract alignment: app and script typechecks validate setup contracts across helper, bridge, schema, view model, and UI code. * Failure path completeness: focused tests cover helper write failures, bridge request failures, and browser loading/error/offline states. * Error information boundaries: focused tests and formatting checks verify redacted diagnostics and browser-safe setup output remain intact. *** ### Task T022 - Write source setup helper tests **Started**: 2026-06-08 02:24 **Completed**: 2026-06-08 02:28 **Duration**: 4 minutes **Notes**: * Added helper tests for declarations, missing config parsing, reviewed target writes, parser compatibility, invalid source/target rejection, redaction, and failed atomic writes. * Focused test run passed: `bun run vitest run scripts/extensions/trend-finder/sources/__tests__/source-setup.test.ts`. **Files Changed**: * `scripts/extensions/trend-finder/sources/__tests__/source-setup.test.ts` - added helper coverage * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T022 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Trust boundary enforcement: tests cover unreviewed source and unsafe target rejection. * Failure path completeness: tests cover parser compatibility and write failure behavior. *** ### Task T023 - Write source setup bridge tests **Started**: 2026-06-08 02:28 **Completed**: 2026-06-08 02:31 **Duration**: 3 minutes **Notes**: * Added bridge tests for method, token, loopback, oversized body, malformed JSON, invalid payloads, GET state, mutation writes, duplicate writes, headers, and redacted write failures. * Focused test run passed: `bun run vitest run scripts/lib/__tests__/trend-finder-source-setup-bridge.test.ts`. **Files Changed**: * `scripts/lib/__tests__/trend-finder-source-setup-bridge.test.ts` - added bridge coverage * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T023 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Duplicate action prevention: tests cover in-flight write rejection. * Error information boundaries: tests assert private paths and token-shaped strings stay out of responses. *** ### Task T024 - Write browser source setup tests **Started**: 2026-06-08 02:31 **Completed**: 2026-06-08 02:34 **Duration**: 3 minutes **Notes**: * Added browser tests for schema defaults, view-model projection, hook loading, panel loading/error/empty states, target controls, pending mutation disabling, warnings, and mutation payloads. * Focused test run passed: `bun run vitest run src/extensions/trend-finder/components/__tests__/source-setup-panel.test.tsx`. **Files Changed**: * `src/extensions/trend-finder/components/__tests__/source-setup-panel.test.tsx` - added schema, hook, view-model, and panel coverage * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T024 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Accessibility and platform compliance: tests exercise labeled controls and disabled pending states. * State freshness on re-entry: hook loading test exercises token-gated bridge reload behavior. *** ### Task T021 - Update source setup documentation **Started**: 2026-06-08 02:19 **Completed**: 2026-06-08 02:24 **Duration**: 5 minutes **Notes**: * Documented the local Source Setup UI, token-gated bridge, private config writes, reviewed target constraints, credential redaction, and unsupported raw Actor edits. **Files Changed**: * `docs/extensions/trend-finder-sources.md` - added Source Setup UI behavior and browser-safe boundary * `docs/sources/apify-source-onboarding.md` - added local setup mutation rules * `docs/apify.md` - added UI-backed private source setup section * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T021 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Trust boundary enforcement: docs explicitly state the reviewed source and target allowlists. * Error information boundaries: docs state that credentials, paths, raw Actor input, Dataset rows, and token-like strings are not browser-visible. *** ### Task T020 - Update fallback and sanitized source config example **Started**: 2026-06-08 02:15 **Completed**: 2026-06-08 02:19 **Duration**: 4 minutes **Notes**: * Added additive `sourceSetup` fallback state to committed live-data example. * Added sanitized source setup editable target notes to the Apify starter config without credentials or private file data. **Files Changed**: * `src/data/live-data.example.json` - added source setup fallback shape * `data/trend-finder.apify-actors.example.json` - documented reviewed editable target fields * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T020 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Contract alignment: committed fallback data carries the additive setup shape expected by the browser schema. * Error information boundaries: examples include only sanitized public target metadata and no credentials. *** ### Task T019 - Update source setup fixtures **Started**: 2026-06-08 02:08 **Completed**: 2026-06-08 02:15 **Duration**: 7 minutes **Notes**: * Added a fixture `sourceSetup` block with configured, missing-credential, restricted, placeholder, invalid-target, and degraded source states. * Included reviewed target field examples without credentials, raw Actor input dumps, Dataset rows, private paths, or raw source payloads. **Files Changed**: * `src/extensions/trend-finder/fixtures.ts` - added source setup fixture state * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T019 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Contract alignment: fixture states exercise the same setup schema consumed by the UI. * Error information boundaries: fixture diagnostics use safe public labels and placeholder messages only. *** ### Task T018 - Wire Source Setup panel into Sources view **Started**: 2026-06-08 02:05 **Completed**: 2026-06-08 02:08 **Duration**: 3 minutes **Notes**: * Added Source Setup visibility menu entry and panel rendering in the Sources view. * Wired `useSourceSetup` with stable hook ordering and disabled bridge loading for inactive disabled/error view states. **Files Changed**: * `src/extensions/trend-finder/views/sources-view.tsx` - added Source Setup panel and visibility entry * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T018 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Accessibility and platform compliance: Source Setup is available through the same visibility controls as other Sources view panels. * State freshness on re-entry: hook re-entry key uses generated run identity and last update time. *** ### Task T017 - Create accessible Source Setup panel **Started**: 2026-06-08 01:55 **Completed**: 2026-06-08 02:05 **Duration**: 10 minutes **Notes**: * Added a dense panel for source readiness, credential/file state, reviewed target controls, warnings, enable toggles, refresh, pending states, and local mutation actions. * Target inputs support text, date, enum, text-list, and URL-list fields with stable labels and focus styles. **Files Changed**: * `src/extensions/trend-finder/components/source-setup-panel.tsx` - created Source Setup panel * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T017 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Accessibility and platform compliance: controls have labels, button names, focus rings, disabled states, and status text. * Duplicate action prevention: panel disables controls while the hook reports busy or per-target pending state. * Failure path completeness: loading, error, offline, empty, and diagnostics states render explicitly. *** ### Task T016 - Create source setup hook **Started**: 2026-06-08 01:49 **Completed**: 2026-06-08 01:55 **Duration**: 6 minutes **Notes**: * Added `useSourceSetup` for loading, mutating, resetting, and revalidating local setup state. * Added explicit idle, loading, ready, saving, error, and offline states with per-mutation pending keys. * Added abort cleanup on unmount and re-entry state reset. **Files Changed**: * `src/extensions/trend-finder/use-source-setup.ts` - created source setup hook * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T016 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Resource cleanup: active requests are aborted on component cleanup. * Duplicate action prevention: in-flight requests are ignored until the current request finishes. * State freshness on re-entry: state resets when the re-entry key changes and reloads through the bridge. * Failure path completeness: offline and request errors are explicit hook states. *** ### Task T015 - Project source setup state into view models **Started**: 2026-06-08 01:44 **Completed**: 2026-06-08 01:49 **Duration**: 5 minutes **Notes**: * Added source setup status, target status, credential label, tone, and aggregate state projections. * Added source setup view models with target summaries, warning labels, last-run labels, and diagnostics. **Files Changed**: * `src/extensions/trend-finder/view-model.ts` - added setup projection helpers * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T015 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Contract alignment: setup status and target status switches are exhaustive via `assertNever`. * Error information boundaries: setup warning and diagnostic labels are sanitized before UI use. *** ### Task T014 - Include safe source setup summaries in generated payloads **Started**: 2026-06-08 01:41 **Completed**: 2026-06-08 01:44 **Duration**: 3 minutes **Notes**: * Collector now loads source setup state from the private source config path and script-only Apify credential presence. * Generated data includes top-level `sourceSetup` state and attaches matching setup summaries to source rows. * Fallback state uses safe diagnostics if setup state cannot be loaded. **Files Changed**: * `scripts/extensions/trend-finder/collector.ts` - added setup state loading and payload wiring * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T014 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Error information boundaries: collector exposes only setup summaries and diagnostics, not private paths, credentials, Actor input, Dataset rows, or raw source payloads. * Failure path completeness: setup summary load failures produce a safe fallback state plus an extension warning. *** ### Task T013 - Register source setup bridge in Vite middleware **Started**: 2026-06-08 01:39 **Completed**: 2026-06-08 01:41 **Duration**: 2 minutes **Notes**: * Registered the source setup bridge with the existing refresh token and loopback predicate. * Passed explicit private config and last-run live-data paths plus a script-only Apify credential presence reader. **Files Changed**: * `vite.config.ts` - registered `registerTrendFinderSourceSetupBridge` * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T013 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Trust boundary enforcement: the bridge uses the same local refresh-token and loopback checks as existing privileged dev endpoints. * Error information boundaries: the Vite registration passes private paths only to script middleware, not browser code. *** ### Task T010 - Create source setup bridge skeleton **Started**: 2026-06-08 01:32 **Completed**: 2026-06-08 01:37 **Duration**: 5 minutes **Notes**: * Added the source setup bridge endpoint module with loopback/token authorization, method gating, bounded JSON body reading, no-store JSON responses, and redacted bridge errors. **Files Changed**: * `scripts/lib/trend-finder-source-setup-bridge.ts` - created bridge skeleton and registration function * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T010 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Trust boundary enforcement: authorization runs before any GET or POST work. * Error information boundaries: bridge errors return stable codes and browser-safe messages. *** ### Task T011 - Implement source setup bridge GET state loading **Started**: 2026-06-08 01:37 **Completed**: 2026-06-08 01:38 **Duration**: 1 minute **Notes**: * GET loads setup declarations, private config state, credential presence, and optional last-run source health. * State loading uses timeout, one retry with backoff, and explicit diagnostics when last-run health cannot be read. **Files Changed**: * `scripts/lib/trend-finder-source-setup-bridge.ts` - added GET state loading * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T011 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * External dependency resilience: file-backed state load has timeout, retry/backoff, and failure diagnostics. * Failure path completeness: last-run health failures degrade to a diagnostic instead of breaking setup state. *** ### Task T012 - Implement source setup bridge mutation handling **Started**: 2026-06-08 01:38 **Completed**: 2026-06-08 01:39 **Duration**: 1 minute **Notes**: * POST handles add-target, update-target, remove-target, and set-enabled mutations through the script-side helper. * Added per-config write locks so duplicate writes return a 409 while another mutation is in flight. **Files Changed**: * `scripts/lib/trend-finder-source-setup-bridge.ts` - added mutation handling and write lock * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T012 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Duplicate action prevention: concurrent mutations against the same config path are rejected while a write is in flight. * Concurrency safety: write lock release is handled in `finally` for success and failure paths. * Failure path completeness: helper errors map to explicit HTTP status and stable codes. *** ### Task T009 - Create browser source setup request helper **Started**: 2026-06-08 01:27 **Completed**: 2026-06-08 01:32 **Duration**: 5 minutes **Notes**: * Added source setup endpoint constants, token retrieval, state GET helper, mutation POST helper, timeout handling, response parsing, and redacted client errors. * Added browser-side mutation schema validation before sending a request. **Files Changed**: * `src/extensions/trend-finder/source-setup.ts` - created endpoint constants and request helpers * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T009 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * External dependency resilience: source setup requests have explicit timeouts and caller-visible failures. * Error information boundaries: browser diagnostics redact token-shaped text before surfacing errors. * Contract alignment: request and response helpers validate payloads against declared schemas. *** ### Task T008 - Extend browser source setup schema **Started**: 2026-06-08 01:21 **Completed**: 2026-06-08 01:27 **Duration**: 6 minutes **Notes**: * Added additive browser-safe source setup enums, schemas, defaults, diagnostics, target summaries, and source summaries. * Added top-level `sourceSetup` defaults to `TrendFinderDataSchema` and optional per-source setup summaries. * Bounded all arrays and browser-visible text fields to keep payloads stable. **Files Changed**: * `src/extensions/trend-finder/schema.ts` - added source setup schemas and defaults * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T008 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Contract alignment: browser schema matches the script-side setup state shape and remains backward compatible with legacy payloads. * Error information boundaries: diagnostics and text fields are bounded before entering browser state. *** ### Task T007 - Add atomic private config write and merge behavior **Started**: 2026-06-08 01:20 **Completed**: 2026-06-08 01:21 **Duration**: 1 minute **Notes**: * Added source record seeding from reviewed declarations only when a mutation targets a reviewed source. * Mutations update only `enabled` and allowlisted `input` fields, preserving existing parser-supported source fields. * Writes go through a temp file and rename, remove temp files on failure, and verify parser compatibility after mutation. **Files Changed**: * `scripts/extensions/trend-finder/sources/source-setup.ts` - added merge, atomic write, compensation, and parser compatibility checks * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T007 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Duplicate action prevention: mutations are idempotent for repeated enable and target update requests. * Concurrency safety: writes use a temp-file transaction boundary and parser verification before returning success. * Failure path completeness: write failures throw typed, redacted setup errors instead of silently continuing. *** ### Task T006 - Create script-side source setup helper **Started**: 2026-06-08 01:08 **Completed**: 2026-06-08 01:20 **Duration**: 12 minutes **Notes**: * Added private config parsing for object, `sources`, `actors`, and array shapes while preserving browser-safe diagnostics. * Added reviewed source summaries, credential presence labels, target summaries, last-run health projection, and explicit mutation schema validation. * Added safe target validation for enums, dates, public URLs, subreddit names, locale codes, bounded arrays, and secret-shaped text. **Files Changed**: * `scripts/extensions/trend-finder/sources/source-setup.ts` - created source setup helper and validation flow * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T006 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Trust boundary enforcement: unknown source IDs and unreviewed target fields throw typed setup errors before writes. * Failure path completeness: malformed config and invalid payloads map to browser-safe diagnostics. * Error information boundaries: helper redacts token-shaped strings and does not return private config paths. *** ### Task T005 - Attach reviewed source setup metadata **Started**: 2026-06-08 01:03 **Completed**: 2026-06-08 01:08 **Duration**: 5 minutes **Notes**: * Added reviewed setup declarations to the ten static Apify source declarations. * Added declaration validation for setup compliance doc alignment, duplicate fields, and enum target value contracts. * Added restricted fallback setup metadata for runtime source records that do not have reviewed declarations. **Files Changed**: * `scripts/extensions/trend-finder/sources/apify-source-config.ts` - attached setup declarations and validation * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T005 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Trust boundary enforcement: unreviewed runtime sources receive unsupported setup metadata instead of editable targets. * Contract alignment: declaration validation catches setup metadata drift before source setup reaches bridge or browser code. *** ### Task T004 - Extend source setup type contracts **Started**: 2026-06-08 01:01 **Completed**: 2026-06-08 01:03 **Duration**: 2 minutes **Notes**: * Added script-side setup target field kinds, target statuses, source setup statuses, credential requirements, setup declarations, and browser-safe summary contracts. * Extended reviewed Apify source declarations with a required `setup` contract. **Files Changed**: * `scripts/extensions/trend-finder/sources/types.ts` - added setup metadata and target status contracts * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T004 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged implementation **BQC Fixes**: * Contract alignment: setup statuses and target field kinds are centralized so script, bridge, and browser schemas can exhaustively handle the same states. *** ### Task T003 - Confirm local bridge hardening patterns **Started**: 2026-06-08 01:00 **Completed**: 2026-06-08 01:01 **Duration**: 1 minute **Notes**: * Confirmed `vite.config.ts` already creates a per-run refresh token and loopback predicate. * Confirmed existing Trend Finder lens and asset bridges provide method gating, token validation, bounded JSON body handling, no-store responses, and redacted error patterns to reuse. **Files Changed**: * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T003 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged verification **BQC Fixes**: * Trust boundary enforcement: confirmed bridge authentication and loopback checks will be applied before reads or writes. * Failure path completeness: confirmed unsupported methods and malformed bodies get explicit browser-safe diagnostics. *** ### Task T002 - Confirm private source config path and gitignored boundary **Started**: 2026-06-08 01:00 **Completed**: 2026-06-08 01:00 **Duration**: 1 minute **Notes**: * Confirmed `data/trend-finder.apify-actors.json` is gitignored. * Confirmed the committed example is sanitized and contains only reviewed source IDs, public Actor IDs, safe sample input, caps, and no credentials. **Files Changed**: * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T002 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged verification **BQC Fixes**: * Error information boundaries: confirmed browser setup must not expose the private file path or credential values. *** ### Task T001 - Verify reviewed source compliance and safe target field prerequisites **Started**: 2026-06-08 00:59 **Completed**: 2026-06-08 01:00 **Duration**: 1 minute **Notes**: * Reviewed Apify onboarding and source compliance docs for the current reviewed source IDs. * Confirmed setup must use static reviewed declarations and allowlisted target fields, with Product Hunt bounded date fields as the only reviewed historical override and other sources remaining current-only. **Files Changed**: * `.spec_system/specs/phase24-session04-source-setup-target-configuration/tasks.md` - marked T001 complete * `.spec_system/specs/phase24-session04-source-setup-target-configuration/implementation-notes.md` - logged verification **BQC Fixes**: * Trust boundary enforcement: confirmed editable setup must validate reviewed source IDs and target fields at the source setup helper and bridge boundary. *** ## Task Log ### 2026-06-08 - Session Start **Environment verified**: * [x] Prerequisites confirmed * [x] Bun 1.3.14 available * [x] Repo-local Vite, Vitest, and TypeScript available through `bun run` * [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/phase24-session04-source-setup-target-configuration/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.