> 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/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase26-session07-hermes-chat-grounding-graph-toolset` **Started**: 2026-06-09 16:45 **Last Updated**: 2026-06-09 17:36

***

## Session Progress

| Metric              | Value   |
| ------------------- | ------- |
| Tasks Completed     | 22 / 22 |
| Estimated Remaining | 0 hours |
| Blockers            | 0       |

***

### Task T022 - Write grounded chat/page tests and run quality checks

**Started**: 2026-06-09 17:34 **Completed**: 2026-06-09 17:36 **Duration**: 2 minutes

**Notes**:

* Added `KnowledgeGraphGroundedChat` tests for loaded composition, active project changes, demo/offline/empty/error states, and no-active-project fallback.
* Updated `KnowledgeGraphPage` tests to assert the `kg-chat-anchor` grounded chat section remains composed with existing page sections.
* Ran the focused Session 07 Vitest set successfully.
* Ran ASCII validation across touched Session 07 source, test, and spec files.

**Files Changed**:

* `src/components/knowledge-graph/__tests__/knowledge-graph-grounded-chat.test.tsx` - Added wrapper coverage.
* `src/components/knowledge-graph/__tests__/knowledge-graph-page.test.tsx` - Added grounded chat page composition assertion.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T022 and completion checklist complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged final test and quality checks.

**BQC Fixes**:

* State freshness on re-entry: wrapper tests assert selected sessions reset on active-project changes.
* Failure path completeness: wrapper tests assert no active project shows an explicit empty state.

***

## Verification

* `bun run test -- src/lib/__tests__/knowledge-graph-hermes-grounding.test.ts src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx src/hooks/__tests__/use-hermes-admin.test.tsx scripts/lib/__tests__/hermes-admin-bridge.test.ts src/components/knowledge-graph/__tests__/knowledge-graph-grounded-chat.test.tsx src/components/knowledge-graph/__tests__/knowledge-graph-page.test.tsx` - passed, 6 files, 91 tests.
* `bun run typecheck` - passed.
* `bunx eslint <Session 07 touched files>` - passed.
* `LC_ALL=C rg -n "[^\\x00-\\x7F]" <Session 07 touched files>` - passed with no matches.

***

### Task T021 - Extend Hermes admin bridge tests

**Started**: 2026-06-09 17:30 **Completed**: 2026-06-09 17:33 **Duration**: 3 minutes

**Notes**:

* Added invalid `toolsets` and strict `yolo` rejection tests.
* Added a bad-token case proving preflight still runs before payload validation.
* Added graphify argv test for `-t graphify` and `--yolo -s graphify` with unsafe-looking prompt text remaining a single argv entry.

**Files Changed**:

* `scripts/lib/__tests__/hermes-admin-bridge.test.ts` - Extended chat bridge coverage.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T021 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged bridge tests.

**BQC Fixes**:

* Trust boundary enforcement: tests assert invalid option payloads fail before spawn.
* Error information boundaries: tests assert invalid toolset responses do not echo the unsafe value.

***

### Task T020 - Extend Hermes admin hook tests

**Started**: 2026-06-09 17:26 **Completed**: 2026-06-09 17:29 **Duration**: 3 minutes

**Notes**:

* Added chat payload serialization coverage for `toolsets` and `yolo`.
* Added invalid tool option rejection coverage before `/__hermes_chat` is called.
* Added cancel/abort coverage that returns chat state to idle.
* Existing duplicate chat submission test remains in place.

**Files Changed**:

* `src/hooks/__tests__/use-hermes-admin.test.tsx` - Extended admin hook chat tests.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T020 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged hook tests.

**BQC Fixes**:

* Duplicate action prevention: existing duplicate guard remains covered.
* Failure path completeness: invalid options and abort state are now covered.

***

### Task T019 - Extend Hermes chat component tests

**Started**: 2026-06-09 17:22 **Completed**: 2026-06-09 17:25 **Duration**: 3 minutes

**Notes**:

* Added tests for starter prefill events and textarea focus.
* Added grounded fresh-chat test covering chip rendering, server-only seed prefix, image private path inclusion in server prompt only, visible-message separation, and tool option forwarding.
* Added resumed-thread test proving seed/options are bypassed.

**Files Changed**:

* `src/components/hermes/chat/__tests__/hermes-chat-tab.test.tsx` - Extended grounded chat coverage.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T019 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged chat tests.

**BQC Fixes**:

* State freshness on re-entry: tests assert resumed sessions bypass fresh grounding.
* Error information boundaries: tests assert private image cache paths do not render in the chat UI.

***

### Task T018 - Write grounding helper tests

**Started**: 2026-06-09 17:19 **Completed**: 2026-06-09 17:21 **Duration**: 2 minutes

**Notes**:

* Added unit tests for deterministic seed context, graph path fallback, safe label/accent projection, graphify guidance, and forbidden secret/write wording.
* Covered the no-active-project null path.

**Files Changed**:

* `src/lib/__tests__/knowledge-graph-hermes-grounding.test.ts` - Added helper coverage.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T018 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged helper tests.

**BQC Fixes**:

* Trust boundary enforcement: tests assert secret/header wording does not enter seed text.

***

### Task T017 - Mount grounded chat in Knowledge Graph page

**Started**: 2026-06-09 17:16 **Completed**: 2026-06-09 17:18 **Duration**: 2 minutes

**Notes**:

* Mounted `KnowledgeGraphGroundedChat` immediately after `KnowledgeGraphStarterChips`.
* Preserved the existing Knowledge Graph hero, project gallery, 3D panel, side rail, ingest card, and connect prompt composition.

**Files Changed**:

* `src/components/knowledge-graph/knowledge-graph-page.tsx` - Mounted the grounded chat wrapper.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T017 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged page mount.

**BQC Fixes**:

* Contract alignment: page still passes its single `useKnowledgeGraph` view into all graph sections.

***

### Task T016 - Implement Knowledge Graph grounded chat wrapper

**Started**: 2026-06-09 17:12 **Completed**: 2026-06-09 17:17 **Duration**: 5 minutes

**Notes**:

* Implemented the anchored `kg-chat-anchor` section.
* Added explicit status copy for live, demo, offline, error, empty, loading, and idle graph states.
* Rendered `HermesChatTab` with active-project grounding and existing Hermes read/admin views.

**Files Changed**:

* `src/components/knowledge-graph/knowledge-graph-grounded-chat.tsx` - Implemented grounded chat wrapper UI and state handling.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T016 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged wrapper implementation.

**BQC Fixes**:

* Failure path completeness: no active project renders an explicit non-chat state instead of seedless grounded chat.
* State freshness on re-entry: active project changes reset selected Hermes thread state.

***

### Task T009 - Define Knowledge Graph grounded chat wrapper

**Started**: 2026-06-09 17:12 **Completed**: 2026-06-09 17:15 **Duration**: 3 minutes

**Notes**:

* Created `KnowledgeGraphGroundedChat` with explicit `view` props.
* Added selected-session state, Hermes reads via `useHermes`, and admin writes via `useHermesAdmin`.
* Derived the chat grounding contract from the active project and graph data through the pure helper.

**Files Changed**:

* `src/components/knowledge-graph/knowledge-graph-grounded-chat.tsx` - Added wrapper props and hook composition.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T009 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged wrapper definition.

**BQC Fixes**:

* State freshness on re-entry: selected Hermes thread is reset when active project or demo mode changes.
* Contract alignment: wrapper passes only the existing Hermes hook views into `HermesChatTab`.

***

### Task T015 - Append graphify flags through bridge argv

**Started**: 2026-06-09 16:58 **Completed**: 2026-06-09 17:11 **Duration**: 13 minutes

**Notes**:

* `/__hermes_chat` now appends `-t <toolsets>` when a validated toolset value is present.
* Boolean `yolo: true` appends `--yolo -s graphify`; other yolo values fail closed or remain disabled.
* All flags are array entries passed to `spawn`; no shell command string is built.

**Files Changed**:

* `scripts/lib/hermes-admin-bridge.ts` - Added validated argv entries for graph-aware chat runs.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T015 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged bridge argv behavior.

**BQC Fixes**:

* Trust boundary enforcement: bridge validation occurs before command resolution and spawn.
* Error information boundaries: unsafe toolset input is not echoed back in bridge responses.
* External dependency resilience: existing timeout and child cleanup paths remain unchanged.

***

### Task T014 - Serialize Hermes admin chat tool options

**Started**: 2026-06-09 16:55 **Completed**: 2026-06-09 17:10 **Duration**: 15 minutes

**Notes**:

* Chat payloads now include validated `toolsets` and strict `yolo` only when options are supplied.
* Empty prompts still fail locally, duplicate submissions still return false while a stream is in-flight, and abort/reset behavior remains unchanged.
* Successful chats still invalidate Hermes session list and selected session detail query keys.

**Files Changed**:

* `src/hooks/use-hermes-admin.ts` - Serialized validated chat options through `/__hermes_chat`.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T014 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged chat serialization work.

**BQC Fixes**:

* Duplicate action prevention: retained `chatInFlightRef` guard.
* Failure path completeness: invalid chat options set a user-visible hook error and return `false`.
* Contract alignment: unchanged query invalidation keys remain after successful sends.

***

### Task T013 - Forward grounded chat tool options

**Started**: 2026-06-09 17:07 **Completed**: 2026-06-09 17:08 **Duration**: 1 minute

**Notes**:

* Added conditional `sendPrompt` forwarding so grounded chats pass `toolsets` and `yolo`.
* Existing non-grounded Hermes chat calls still invoke `sendPrompt(prompt, sessionId)`.
* Resumed sessions do not receive grounding options because `freshGrounding` is disabled when a selected session is active.

**Files Changed**:

* `src/components/hermes/chat/hermes-chat-tab.tsx` - Forwarded optional chat tool options for grounded fresh chats.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T013 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged send option forwarding.

**BQC Fixes**:

* Contract alignment: admin hook options are only sent when the chat tab receives a valid grounding contract.

***

### Task T012 - Implement visible grounding chip

**Started**: 2026-06-09 17:06 **Completed**: 2026-06-09 17:07 **Duration**: 1 minute

**Notes**:

* Added a fresh-chat-only grounding chip with `Chatting with <project>` copy.
* Used bounded text from the grounding helper and safe optional accent border styling.
* Added title and `aria-label` so truncated project names remain accessible.

**Files Changed**:

* `src/components/hermes/chat/hermes-chat-tab.tsx` - Added the grounding chip in the chat header.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T012 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged chip implementation.

**BQC Fixes**:

* Accessibility and platform compliance: chip includes accessible label and title.
* Contract alignment: chip only renders when a fresh grounded context exists.

***

### Task T011 - Implement first-turn invisible seed composition

**Started**: 2026-06-09 17:05 **Completed**: 2026-06-09 17:06 **Duration**: 1 minute

**Notes**:

* First-turn detection now applies only when there is no selected session and no local messages.
* Server prompt composition includes seed context, image prefixes, and the user prompt.
* Local user bubbles continue to show only the user prompt and attachment summary.
* Existing selected-session and demo-mode reset behavior remains in place.

**Files Changed**:

* `src/components/hermes/chat/hermes-chat-tab.tsx` - Composed server-only grounding seed for first fresh turn.
* `src/components/hermes/chat/chat-types.ts` - Added shared prompt composition helper used by the chat tab.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T011 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged first-turn composition.

**BQC Fixes**:

* State freshness on re-entry: selected thread/demo changes reset local draft, attachments, errors, and chat state.
* Contract alignment: display message content remains separate from server prompt content.

***

### Task T010 - Implement Hermes starter prefill behavior

**Started**: 2026-06-09 17:04 **Completed**: 2026-06-09 17:05 **Duration**: 1 minute

**Notes**:

* Implemented `hermes-chat-prefill` handling for string and object payload shapes.
* Repeated events replace the current draft and increment a focus request key.
* The listener is browser-only and removed during cleanup.

**Files Changed**:

* `src/components/hermes/chat/hermes-chat-tab.tsx` - Added prefill event parsing and listener behavior.
* `src/components/hermes/chat/chat-composer.tsx` - Focuses the textarea when requested by the parent.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T010 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged prefill behavior.

**BQC Fixes**:

* Resource cleanup: event listener is removed on unmount.
* Accessibility and platform compliance: focus moves to the native textarea after prefill.

***

### Task T006 - Define Hermes chat grounding scaffolding

**Started**: 2026-06-09 17:01 **Completed**: 2026-06-09 17:04 **Duration**: 3 minutes

**Notes**:

* Added optional `grounding` props to `HermesChatTab`.
* Added focus request state for starter prefill events.
* Added a browser-only prefill listener with cleanup on unmount.

**Files Changed**:

* `src/components/hermes/chat/hermes-chat-tab.tsx` - Added grounding props and prefill listener scaffolding.
* `src/components/hermes/chat/chat-composer.tsx` - Added composer focus request support.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T006 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged chat scaffolding.

**BQC Fixes**:

* Resource cleanup: prefill listener is removed on component unmount.
* State freshness on re-entry: existing selected-session and demo-mode reset path is preserved.

***

### Task T008 - Add bridge chat option validation

**Started**: 2026-06-09 16:58 **Completed**: 2026-06-09 17:00 **Duration**: 2 minutes

**Notes**:

* Added bridge-side validation for bounded `toolsets` strings.
* Added strict `yolo` parsing so only boolean `true` enables graph mode.
* Kept validation after the existing POST, loopback, token, and admin preflight and before Hermes command resolution/spawn.

**Files Changed**:

* `scripts/lib/hermes-admin-bridge.ts` - Added chat option validators and argv option preparation.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T008 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged bridge validation.

**BQC Fixes**:

* Trust boundary enforcement: optional chat fields are validated inside the bridge boundary.
* Error information boundaries: invalid toolset values return bounded generic errors without echoing unsafe input.

***

### Task T007 - Extend Hermes admin chat send options

**Started**: 2026-06-09 16:55 **Completed**: 2026-06-09 16:57 **Duration**: 2 minutes

**Notes**:

* Extended `HermesChatView.sendPrompt` to accept an optional third `HermesChatSendOptions` argument.
* Added client-side validation for bounded toolset strings and serialized `yolo` only when strictly true.
* Preserved the existing prompt trim, duplicate in-flight guard, abort controller, SSE read, and query invalidation flow.

**Files Changed**:

* `src/hooks/use-hermes-admin.ts` - Added chat option serialization and validation.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T007 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged hook extension.

**BQC Fixes**:

* Duplicate action prevention: kept `chatInFlightRef` as the first write guard before network execution.
* Trust boundary enforcement: validated optional toolset values before crossing into the admin bridge.
* Failure path completeness: invalid options now return a visible chat error instead of silently dropping fields.

***

### Task T005 - Create Knowledge Graph Hermes grounding helper

**Started**: 2026-06-09 16:52 **Completed**: 2026-06-09 16:54 **Duration**: 2 minutes

**Notes**:

* Added a pure grounding builder that returns seed context, visible project label, safe accent color, and `graphify` chat options.
* Included deterministic fallback text for missing graph paths.
* Kept the seed focused on read-only graph grounding and avoided token, header, private bridge, or direct mutation instructions.

**Files Changed**:

* `src/lib/knowledge-graph-hermes-grounding.ts` - Created deterministic grounding helper.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T005 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged helper creation.

**BQC Fixes**:

* Error information boundaries: bounded project label, description, and path text before injecting into prompt seed.
* Contract alignment: centralized graphify send options with the prompt seed builder.

***

### Task T004 - Add Hermes chat grounding contracts

**Started**: 2026-06-09 16:49 **Completed**: 2026-06-09 16:51 **Duration**: 2 minutes

**Notes**:

* Added `HermesChatGrounding`, `HermesChatSendOptions`, and the shared prefill event constant.
* Added `composeHermesChatPrompt` so seed context, image prefixes, and display prompt separation are deterministic.
* Exported the new contracts from the chat module barrel.

**Files Changed**:

* `src/components/hermes/chat/chat-types.ts` - Added grounding/send-option types and prompt composition helper.
* `src/components/hermes/chat/index.ts` - Exported new chat grounding contracts.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T004 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged type contract work.

**BQC Fixes**:

* Contract alignment: added one shared prompt composition helper to avoid component/hook payload shape drift.

***

### Task T003 - Confirm Hermes admin gate and chat send path

**Started**: 2026-06-09 16:46 **Completed**: 2026-06-09 16:48 **Duration**: 2 minutes

**Notes**:

* Confirmed `useHermesAdmin().chat.sendPrompt` trims prompts, blocks duplicates with `chatInFlightRef`, uses `AbortController`, parses SSE, and invalidates Hermes sessions and session detail after success.
* Confirmed `/__hermes_chat` still requires POST, loopback, per-run token, and `HERMES_DASHBOARD_ADMIN=1` before reading payload or spawning Hermes.
* Confirmed bridge tests already cover preflight inventory, missing binary, argv spawn, streaming, and provider auth classification.

**Files Changed**:

* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T003 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged admin-gate verification.

**BQC Fixes**:

* N/A - verification task only.

***

### Task T002 - Inspect upstream Hermes and codegraph behavior

**Started**: 2026-06-09 16:45 **Completed**: 2026-06-09 16:47 **Duration**: 2 minutes

**Notes**:

* Reviewed upstream `codegraph.tsx` behavior for compact graph seed context, active-project grounding, and chat panel placement.
* Reviewed upstream chat bridge behavior in `vite.config.ts` for `toolsets`, strict `yolo`, `-t`, and `--yolo -s graphify` argv handling.
* Used upstream only as a behavior reference; implementation will use the repo's modular Hermes chat/admin bridge.

**Files Changed**:

* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T002 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged upstream mapping.

**BQC Fixes**:

* N/A - verification task only.

***

### Task T001 - Verify prerequisite session outputs and current shapes

**Started**: 2026-06-09 16:43 **Completed**: 2026-06-09 16:46 **Duration**: 3 minutes

**Notes**:

* Confirmed the current session resolves to `phase26-session07-hermes-chat-grounding-graph-toolset`.
* Confirmed Knowledge Graph page state includes active project, graph, registry, Hermes projection, starter chips, connect prompt, token hook, and admin hook outputs from Sessions 05 and 06.
* Confirmed starter chips dispatch `hermes-chat-prefill` and scroll to `kg-chat-anchor`.
* Confirmed `HermesChatTab` is exported from `src/components/hermes/chat/index.ts`.

**Files Changed**:

* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/tasks.md` - Marked T001 complete.
* `.spec_system/specs/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md` - Logged setup verification.

**BQC Fixes**:

* N/A - verification task only.

***

## Task Log

### 2026-06-09 - 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/phase26-session07-hermes-chat-grounding-graph-toolset/implementation-notes.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.