> For the complete documentation index, see [llms.txt](https://faction-os.gitbook.io/faction-os-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md).

# Implementation Notes

**Session ID**: `phase03-session03-subagent-lineage-and-mission-graph-runtime` **Package**: Cross-cutting (`packages/protocol`, `apps/hooks`, `apps/server`) **Started**: 2026-05-29 12:12 **Last Updated**: 2026-05-29 12:12

***

## Session Progress

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

***

## Task Log

### 2026-05-29 - Session Start

**Environment verified**:

* [x] Prerequisites confirmed
* [x] Tools available via `node_modules/.bin`
* [x] Directory structure ready
* [x] No database layer configured for this session

***

### Task T001 - Verify prerequisites and opaque subagent baseline

**Started**: 2026-05-29 12:10 **Completed**: 2026-05-29 12:12 **Duration**: 2 minutes

**Notes**:

* Confirmed spec-system analysis resolves current session `phase03-session03-subagent-lineage-and-mission-graph-runtime`.
* Confirmed Session 01 and Session 02 are listed as completed in `.spec_system/state.json`.
* Confirmed Session 03 gap matrix currently routes subagent spawn and completion hooks as opaque mission events.

**Files Changed**:

* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked prerequisite verification complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded setup verification.

***

### Task T002 - Create implementation notes and security placeholders

**Started**: 2026-05-29 12:12 **Completed**: 2026-05-29 12:13 **Duration**: 1 minute

**Notes**:

* Created session implementation notes using the apex-spec workflow structure.
* Created initial security compliance artifact with local-only lineage and privacy constraints.

**Files Changed**:

* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - initialized session progress log.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/security-compliance.md` - initialized session security posture.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked artifact setup complete.

***

### Task T003 - Confirm entry points and validation commands

**Started**: 2026-05-29 12:13 **Completed**: 2026-05-29 12:13 **Duration**: 1 minute

**Notes**:

* Confirmed root npm workspace scripts for format, lint, typecheck, and test.
* Confirmed package-local typecheck scripts for `packages/protocol` and `apps/server`.
* Confirmed hooks use Vitest through the root test runner and package-local source fixtures.
* Confirmed toolchain is available through `node_modules/.bin`, so validation commands should run with `PATH="$PWD/node_modules/.bin:$PATH"`.

**Files Changed**:

* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked validation command confirmation complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded focused command set.

***

### Task T004 - Create subagent lineage domain contracts

**Started**: 2026-05-29 12:13 **Completed**: 2026-05-29 12:17 **Duration**: 4 minutes

**Notes**:

* Added protocol-owned lineage constants, state vocabulary, degraded reasons, mission references, graph nodes, edges, snapshots, and compact event snapshots.
* Kept the contract local-only and data-only; it does not imply spawning, stopping, or controlling subagents.

**Files Changed**:

* `packages/protocol/src/lineage.ts` - new lineage and mission graph contract module.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked lineage contract task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded protocol contract work.

***

### Task T005 - Add mission lineage references

**Started**: 2026-05-29 12:17 **Completed**: 2026-05-29 12:18 **Duration**: 1 minute

**Notes**:

* Added optional `parentMissionId`, `childMissionIds`, and `subagentLineage` fields to `Mission`.
* Existing mission payloads remain compatible because the new fields are optional.

**Files Changed**:

* `packages/protocol/src/missions.ts` - added optional mission graph references.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked mission contract task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded contract update.

***

### Task T006 - Promote subagent ingest contracts

**Started**: 2026-05-29 12:18 **Completed**: 2026-05-29 12:21 **Duration**: 3 minutes

**Notes**:

* Added `LINEAGE_HOOK_TYPES` for `subagent_spawn` and `subagent_complete`.
* Added typed spawn and completion ingest payload shapes with bounded metadata fields and explicit degraded-state fields.
* Kept `git_dirty` in the opaque hook family so unrelated opaque compatibility remains intact.

**Files Changed**:

* `packages/protocol/src/ingest.ts` - added lineage hook vocabulary and typed subagent payload contracts.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked ingest contract task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded ingest contract update.

***

### Task T007 - Add lineage WebSocket frames

**Started**: 2026-05-29 12:21 **Completed**: 2026-05-29 12:22 **Duration**: 1 minute

**Notes**:

* Added `subagent_lineage_update` and `mission_graph_update` protocol event types.
* Frame payloads reference compact lineage updates and graph snapshots only; there are no prompt, command, path, token, terminal, or transcript fields in the event contracts.

**Files Changed**:

* `packages/protocol/src/events.ts` - added lineage update event interfaces and union members.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked WebSocket protocol task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded event contract update.

***

### Task T008 - Create bounded mission graph manager

**Started**: 2026-05-29 12:22 **Completed**: 2026-05-29 12:30 **Duration**: 8 minutes

**Notes**:

* Added an in-memory mission graph manager with bounded node count, deterministic snapshot ordering, compact event snapshots, duplicate event keys, and degraded missing-ID state.
* The manager is data-only and does not execute local actions or control subagent processes.

**Files Changed**:

* `apps/server/src/managers/missionGraph.ts` - new mission graph manager.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked mission graph manager task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded manager implementation.

**BQC Fixes**:

* Duplicate action prevention: duplicate lineage events are keyed and returned as duplicate mutations instead of creating repeated graph entries (`apps/server/src/managers/missionGraph.ts`).
* State freshness on re-entry: snapshots are cloned on read so callers do not mutate stored graph state (`apps/server/src/managers/missionGraph.ts`).

***

### Task T009 - Harden subagent ID detection

**Started**: 2026-05-29 12:30 **Completed**: 2026-05-29 12:32 **Duration**: 2 minutes

**Notes**:

* Added bounded subagent ID sanitization and explicit degraded reasons for missing, malformed, and oversized IDs.
* Kept transcript path parsing local to the hook helper; returned payload data contains only safe IDs and degraded status.

**Files Changed**:

* `apps/hooks/src/_lib.js` - added `SUBAGENT_ID_MAX_LENGTH`, `detectSubagentLineage`, and `sanitizeSubagentId`.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked hook helper hardening complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded hook helper work.

**BQC Fixes**:

* Trust boundary enforcement: transcript-derived IDs are sanitized and length-bounded before any hook payload can send them (`apps/hooks/src/_lib.js`).
* Error information boundaries: malformed transcript paths become degraded reason codes, not raw path output (`apps/hooks/src/_lib.js`).

***

### Task T010 - Export lineage contracts

**Started**: 2026-05-29 12:32 **Completed**: 2026-05-29 12:32 **Duration**: 1 minute

**Notes**:

* Re-exported protocol lineage contracts from the package root for server, hooks-adjacent tests, and future clients.

**Files Changed**:

* `packages/protocol/src/index.ts` - added lineage contract export.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked package export task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded export update.

***

### Task T011 - Update subagent spawn payload shaping

**Started**: 2026-05-29 12:32 **Completed**: 2026-05-29 12:36 **Duration**: 4 minutes

**Notes**:

* Spawn payloads now send sanitized `subagentId`, optional sanitized `parentSubagentId`, bounded `subagentType`, bounded `description`, and degraded reason codes.
* Removed raw prompt transfer from the spawn payload; prompt text is only counted in local diagnostics.

**Files Changed**:

* `apps/hooks/src/factionos-subagent-spawn.js` - updated lineage payload shaping and removed prompt field from posted payload.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked spawn hook task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded hook spawn update.

**BQC Fixes**:

* Trust boundary enforcement: subagent IDs are sanitized before posting (`apps/hooks/src/factionos-subagent-spawn.js`).
* Error information boundaries: raw prompt and transcript path are not posted (`apps/hooks/src/factionos-subagent-spawn.js`).

***

### Task T012 - Update subagent completion payload shaping

**Started**: 2026-05-29 12:36 **Completed**: 2026-05-29 12:38 **Duration**: 2 minutes

**Notes**:

* Completion payloads now send sanitized subagent IDs, bounded summaries, and missing/malformed/oversized ID degraded reasons.
* Transcript paths remain hook-local and are not sent to the server.

**Files Changed**:

* `apps/hooks/src/factionos-subagent-complete.js` - updated typed completion payload shaping.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked completion hook task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded hook completion update.

**BQC Fixes**:

* Trust boundary enforcement: completion IDs are sanitized before posting (`apps/hooks/src/factionos-subagent-complete.js`).
* Error information boundaries: raw transcript paths are converted to compact degraded reason codes (`apps/hooks/src/factionos-subagent-complete.js`).

***

### Task T013 - Update event ingest normalization

**Started**: 2026-05-29 12:38 **Completed**: 2026-05-29 12:43 **Duration**: 5 minutes

**Notes**:

* Added first-class `subagent_spawn` and `subagent_complete` dispatch kinds.
* Added server-side lineage metadata normalization with ID sanitization, length bounds, and explicit degraded reason mapping.
* Existing malformed non-object request behavior remains unchanged.

**Files Changed**:

* `apps/server/src/lib/eventIngest.ts` - added lineage dispatch and metadata normalization helpers.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked ingest normalization complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded normalization update.

**BQC Fixes**:

* Trust boundary enforcement: `/event` lineage IDs are sanitized server-side even when hook helpers already sanitized them (`apps/server/src/lib/eventIngest.ts`).
* Failure path completeness: malformed or missing lineage IDs map to degraded reason codes instead of crashing or echoing raw input (`apps/server/src/lib/eventIngest.ts`).

***

### Task T014 - Wire typed lineage handling into event route

**Started**: 2026-05-29 12:43 **Completed**: 2026-05-29 12:50 **Duration**: 7 minutes

**Notes**:

* Added first-class route handling for `subagent_spawn` and `subagent_complete`.
* Emitted compact `subagent_lineage_update` and `mission_graph_update` frames from route handling.
* Missing hero and missing mission conditions now produce bounded degraded mission events; unsupported named events remain on the opaque fallback path.

**Files Changed**:

* `apps/server/src/routes/event.ts` - added typed lineage route handlers and WebSocket emission helpers.
* `apps/server/src/server.ts` - provisionally passed a mission graph manager into the event route so route wiring composes.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked event route wiring complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded route wiring.

**BQC Fixes**:

* Failure path completeness: missing hero and missing mission lineage cases emit bounded degraded events instead of silently dropping the payload (`apps/server/src/routes/event.ts`).
* Error information boundaries: degraded mission events include only lineage IDs and reason codes, not raw prompt, path, command, token, or transcript fields (`apps/server/src/routes/event.ts`).

***

### Task T015 - Pass mission graph manager through server composition

**Started**: 2026-05-29 12:49 **Completed**: 2026-05-29 12:51 **Duration**: 2 minutes

**Notes**:

* Instantiated `MissionGraphManager` alongside existing in-memory managers.
* Passed the manager only to `eventRouter`; auth, CORS, Origin, rate-limit, and body-size middleware order is unchanged.

**Files Changed**:

* `apps/server/src/server.ts` - instantiated and passed the mission graph manager.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked server composition task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded composition update.

***

### Task T016 - Add mission manager relationship helpers

**Started**: 2026-05-29 12:51 **Completed**: 2026-05-29 12:58 **Duration**: 7 minutes

**Notes**:

* Added child mission creation, parent-child link helpers, and lineage reference updates to `MissionManager`.
* Updated subagent spawn route handling to create/link child missions when a parent mission and safe subagent ID are available.
* Updated completion handling to complete linked child missions idempotently.

**Files Changed**:

* `apps/server/src/managers/missionManager.ts` - added `startChild`, `linkChild`, and `setSubagentLineage`.
* `apps/server/src/routes/event.ts` - wired child mission creation, completion, and mission update frames around graph mutations.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked relationship helper task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded relationship helper work.

**BQC Fixes**:

* Duplicate action prevention: parent mission child lists reject duplicate child IDs (`apps/server/src/managers/missionManager.ts`).
* Contract alignment: mission records now carry the same parent and subagent lineage references emitted in graph update frames (`apps/server/src/routes/event.ts`).

***

### Task T017 - Preserve lineage redaction boundaries

**Started**: 2026-05-29 12:58 **Completed**: 2026-05-29 13:00 **Duration**: 2 minutes

**Notes**:

* Added deterministic lineage ID placeholder redaction.
* Extended archive/export recursive redaction to cover `subagentId`, `parentSubagentId`, and `transcriptPath` fields.
* Mission export redaction now includes optional `subagentLineage`.

**Files Changed**:

* `apps/server/src/lib/sessionPrivacy.ts` - added lineage redaction placeholders and recursive mission lineage redaction.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked redaction task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded redaction work.

**BQC Fixes**:

* Error information boundaries: archive/export recursion redacts lineage identifiers and transcript path fields in nested graph payloads (`apps/server/src/lib/sessionPrivacy.ts`).

***

### Task T018 - Include safe lineage fields in export output

**Started**: 2026-05-29 13:00 **Completed**: 2026-05-29 13:01 **Duration**: 1 minute

**Notes**:

* Added deterministic mission CSV columns for parent mission, child count, lineage state, degraded reason, and redacted subagent ID.
* JSON export uses the existing redacted mission snapshot, now including redacted optional `subagentLineage`.

**Files Changed**:

* `apps/server/src/lib/exportSession.ts` - added lineage-aware mission CSV columns.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked export lineage task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded export update.

***

### Task T019 - Update API and hook docs

**Started**: 2026-05-29 13:01 **Completed**: 2026-05-29 13:07 **Duration**: 6 minutes

**Notes**:

* Updated API docs to describe typed subagent lineage behavior, compact WebSocket graph frames, degraded fallback, and continued opaque compatibility for unsupported named events.
* Preserved explicit boundaries: no subagent control actions, no remote execution, no hosted lineage sync.

**Files Changed**:

* `docs/api/README_api.md` - updated concise API and orchestration status summary.
* `docs/api/event-api-hook-contracts.md` - updated source-backed ingest, WebSocket, hook, and Phase 03 orchestration contracts.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked docs task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded documentation update.

***

### Task T020 - Write protocol lineage contract tests

**Started**: 2026-05-29 13:07 **Completed**: 2026-05-29 13:11 **Duration**: 4 minutes

**Notes**:

* Added Vitest coverage for lineage state and degraded vocabularies, mission relationship fields, full and compact graph snapshots, and WebSocket discriminants.
* Added negative assertions that compact lineage frame examples do not include prompt, command, transcript, or token fields.

**Files Changed**:

* `packages/protocol/tests/lineage.test.ts` - new protocol lineage contract tests.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked protocol test task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded protocol test coverage.

***

### Task T021 - Write hook payload lineage tests

**Started**: 2026-05-29 13:11 **Completed**: 2026-05-29 13:14 **Duration**: 3 minutes

**Notes**:

* Updated hook payload fixture assertions for typed lineage fields and no raw prompt transfer in spawn payloads.
* Added helper-level tests for absent transcript paths, malformed transcript paths, Windows-style paths, and oversized ID bounds.

**Files Changed**:

* `apps/hooks/tests/hookPayloads.test.js` - added typed lineage and helper tests.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked hook test task complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded hook test coverage.

***

### Task T022 - Write server ingest lineage tests

**Started**: 2026-05-29 13:14 **Completed**: 2026-05-29 13:23 **Duration**: 9 minutes

**Notes**:

* Updated the event route harness to include `MissionGraphManager`.
* Added tests for typed spawn/completion, parent-child mission links, missing IDs, malformed IDs, oversized IDs, duplicate events, and sensitive field exclusion.
* Tightened hook/server sanitizers so malformed IDs are explicitly labeled `malformed_subagent_id`.

**Files Changed**:

* `apps/server/tests/eventIngest.test.ts` - added lineage ingest coverage.
* `apps/hooks/src/_lib.js` - labeled invalid ID characters as malformed.
* `apps/server/src/lib/eventIngest.ts` - labeled invalid ID characters as malformed.
* `apps/hooks/tests/hookPayloads.test.js` - updated malformed ID expectation.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked server ingest tests complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded server test coverage.

***

### Task T023 - Write export and privacy lineage tests

**Started**: 2026-05-29 13:23 **Completed**: 2026-05-29 13:28 **Duration**: 5 minutes

**Notes**:

* Added CSV and JSON export tests for lineage columns and redacted local lineage IDs.
* Added archive redaction coverage for nested lineage graph payloads and transcript path fields.

**Files Changed**:

* `apps/server/tests/exportSession.test.ts` - added lineage export and privacy tests.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked export/privacy tests complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded export/privacy coverage.

***

### Task T024 - Run focused validation and hygiene checks

**Started**: 2026-05-29 13:28 **Completed**: 2026-05-29 13:35 **Duration**: 7 minutes

**Notes**:

* Ran protocol and server typechecks successfully.
* Ran focused Vitest coverage for protocol lineage, ingest vocabulary, hook payloads, server ingest, and export privacy successfully.
* Ran existing WebSocket tests successfully.
* Ran Biome check on touched TypeScript and JavaScript files successfully after formatting.
* Ran ASCII, LF, and `git diff --check` hygiene successfully.

**Files Changed**:

* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/tasks.md` - marked validation task and completion checklist complete.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/implementation-notes.md` - recorded validation results.
* `.spec_system/specs/phase03-session03-subagent-lineage-and-mission-graph-runtime/security-compliance.md` - recorded session security findings and validation posture.

**Validation Commands**:

* `PATH="$PWD/node_modules/.bin:$PATH" npm --workspace packages/protocol run typecheck` - pass.
* `PATH="$PWD/node_modules/.bin:$PATH" npm --workspace apps/server run typecheck` - pass.
* `PATH="$PWD/node_modules/.bin:$PATH" npx vitest run packages/protocol/tests/lineage.test.ts packages/protocol/tests/ingest.test.ts apps/hooks/tests/hookPayloads.test.js apps/server/tests/eventIngest.test.ts apps/server/tests/exportSession.test.ts` - 49 tests pass.
* `PATH="$PWD/node_modules/.bin:$PATH" npx vitest run apps/server/tests/websocket.test.ts` - 6 tests pass.
* `PATH="$PWD/node_modules/.bin:$PATH" npx biome check ...` - pass for touched TypeScript and JavaScript files.
* ASCII check over changed files - pass.
* LF check over changed files - pass.
* `git diff --check` - pass.

***


---

# 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://faction-os.gitbook.io/faction-os-docs/.spec_system/archive/sessions/phase03-session03-subagent-lineage-and-mission-graph-runtime/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.