> 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/phase19-session12-terminal-and-containers/spec.md). # Session Specification **Session ID**: `phase19-session12-terminal-and-containers` **Phase**: 19 - Orchestration Command Center Execution **Status**: Not Started **Created**: 2026-06-26 **Package**: null **Package Stack**: mixed *** ## 1. Session Overview This session turns terminal and container execution from unavailable posture into owned command-center capabilities with explicit probes, permission gates, audit-safe execution records, bounded output, cleanup behavior, and scoped UI. It adds the server runtime managers and web surfaces needed for terminal sessions, container readiness, and isolated spawn previews while preserving the local-first execution boundary. It is next because Phase 19 Sessions 06, 07, 08, and 09 completed the executor registry, provider diagnostics, file/git execution patterns, and hero lineage surfaces. Those foundations now provide the route, manager, guarded-action, execution-run, and UI patterns that terminal and container work can extend without inventing a separate debug subsystem. The session stays fail-closed. If PTY support, Docker, Apple Containers, browser dependencies, image state, auth mount, worktree mount, or network/port requirements are missing, the command center reports structured unavailable states with fallback reasons. Broad command-center rows show status, duration, owner, exit state, and safe summaries only; bounded terminal output is confined to the scoped terminal drawer. *** ## 2. Objectives 1. Add shared terminal, container, and isolation readiness contracts for probes, sessions, lifecycle actions, execution runs, fallback reasons, and bounded output metadata. 2. Add server-owned terminal and container managers with injectable adapters, output caps, timeout/kill/restart cleanup, duplicate-trigger protection, and guarded executor registry integration. 3. Add web terminal drawer and isolation capability UI that renders loading, empty, error, offline, unavailable, executing, exited, killed, and failed states with product-facing copy only. 4. Cover protocol, server, route, executor, web API, store, and component behavior with focused tests plus validation commands. *** ## 3. Prerequisites ### Required Sessions * [x] `phase19-session03-web-shell-and-store` - command-center store, shell, snapshot hydration, tabs, and drawer state * [x] `phase19-session05-attention-and-permissions` - permission and attention decision patterns for guarded actions * [x] `phase19-session06-executor-registry` - guarded-action approval boundary and executor capability registry * [x] `phase19-session07-provider-diagnostics` - capability posture and recovery UI patterns * [x] `phase19-session08-file-and-git` - bounded local execution and execution-run recording patterns * [x] `phase19-session09-heroes-and-lineage` - hero lifecycle records and isolation-mode metadata ### Required Tools Or Knowledge * Node 26.2.0+ and npm workspaces * Vitest root test runner * Existing guarded-action, command-center, executor registry, and Git workbench patterns * Existing isolation diagnostics and security boundary in `docs/isolation-and-sandbox.md` * Docker and Apple Containers command-line tools are optional runtime probes, not development prerequisites ### Environment Requirements * Local workspace dependencies installed with `npm install` * Local server auth, CORS, rate-limit, and WebSocket origin middleware remain inherited by new routes * No hosted account, War Room Worker, remote tunnel, provider credential, or production Docker daemon required for tests *** ## 4. Scope ### In Scope (MVP) * Operators can probe terminal capability, see PTY availability, shell label, cwd label, active session count, timeout policy, output cap, cleanup posture, and fallback reason. * Operators can request, approve, run, observe, send input to, kill, restart, and record bounded terminal commands through guarded terminal execution with duplicate-trigger prevention while in-flight. * Terminal sessions keep bounded output, exit state, exit code, duration, owner, result attachment, and cleanup status while broad command-center rows avoid raw command bodies and broad output. * Operators can probe Docker and Apple Containers readiness, image state, browser dependency posture, auth mount posture, worktree mount posture, network/port profile, provider/runtime availability, cleanup posture, and fallback reason. * Isolated hero spawn is represented as a guarded lifecycle action when probes pass, with explicit unavailable or preview-only states when runtime gates are missing. * The web cockpit renders a scoped terminal drawer and isolation capability rows with loading, empty, error, offline, unavailable, running, exited, killed, restarted, and failed states. * Protocol, server, route, executor registry, web API, store, component, docs, and focused validation coverage are updated. ### Out Of Scope (Deferred) * Remote access tunnels - Reason: the Session 12 stub excludes tunnel creation and the current remote-access family remains policy-blocked. * Broad terminal output rendering outside scoped details - Reason: Phase 19 and isolation docs require terminal output to stay out of broad rows, exports, replay, Worker transfer, and diagnostics. * Arbitrary hosted or remote executor behavior - Reason: hosted, Worker, and remote execution remain separate future threat models. * Persisted terminal transcripts - Reason: this session stores bounded runtime output for scoped local details and audit summaries only, not durable transcript archives. * Full container image build pipeline - Reason: this session probes image state and can run an isolated spawn only when a ready image/runtime is already available. * Trusted rollback for terminal side effects - Reason: terminal commands can have external side effects, so rollback is explicit manual guidance unless a later family-specific implementation proves more. *** ## 5. Technical Approach ### Architecture Protocol changes lead the cross-package work. `packages/protocol/src/orchestrationCommandCenter.ts` and `packages/protocol/src/isolation.ts` will define terminal session, terminal action, container runtime, isolation profile, fallback reason, and execution-result metadata before server and web behavior consume them. Request-only raw command bodies stay out of persistent command-center records, WebSocket snapshots, logs, docs examples, and broad UI rows. The server will add manager-owned runtime boundaries. `TerminalSessionManager` will own PTY adapter probing, session lifecycle, output ring buffers, stdin, kill, restart, timeout cleanup, exit state, and result attachment. It will use an injectable adapter so tests do not require a real PTY, and runtime will fail closed when PTY support is absent. `ContainerRuntimeManager` will use injectable bounded command probes for Docker and Apple Containers, image state, browser dependencies, mount readiness, network/port posture, cleanup posture, and isolated spawn preview/execute readiness. Executor registry integration will follow the file/git pattern. Terminal and container guarded actions become `executor_ready` only when their manager probes pass. Approved terminal/container actions create or update command-center execution runs with idempotency, timeout, cleanup, result status, failure code, unavailable reason, and safe summaries. Capability refresh and diagnostics update the command-center executor records without invoking execution. The web app will keep terminal details scoped. `orchestrationApi.ts` will expose typed terminal/container clients, `terminalContainers.ts` will normalize safe view models, and focused components will render terminal output only inside the selected terminal drawer. Existing Orchestration panes, drawers, and executor cards will show compact state, fallback reasons, and recent run summaries without raw command bodies. ### Design Patterns * Protocol-first contracts: shared terminal/container shapes and parsers are added before server or web behavior. * Manager-owned lifecycle: PTY processes, output buffers, timeouts, restart/kill, container probes, and cleanup stay behind server managers. * Guarded execution boundary: execution requires capability readiness, approval, expected revision or idempotency, validation, and route-level in-flight protection. * Pure normalization before store mutation: web helpers reject malformed or raw payloads before updating Zustand state. * Product-surface UI: user-facing surfaces show workflow state and safe labels; diagnostics remain explicit diagnostics surfaces. *** ## 6. Deliverables ### Files To Create | File | Purpose | Est. Lines | | -------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `apps/server/src/managers/terminalSessionManager.ts` | PTY adapter boundary, terminal lifecycle, output cap, timeout, input, kill, restart, exit state, cleanup, and result attachment | \~360 | | `apps/server/src/managers/containerRuntimeManager.ts` | Docker and Apple Containers probe manager, image/browser/auth/worktree/network readiness, fallback reasons, cleanup, and isolated spawn preview/run helpers | \~320 | | `apps/server/src/lib/terminalContainerValidation.ts` | Request parsers for terminal command preview/run/input/kill/restart, container probe, isolated spawn preview, and guarded execution metadata | \~240 | | `apps/server/src/routes/terminalContainers.ts` | Local REST routes for terminal snapshots, lifecycle actions, container probes, and isolated spawn preview/execute responses | \~260 | | `apps/server/tests/terminalSessionManager.test.ts` | Unit tests for PTY probing, output caps, timeout cleanup, input, kill, restart, exit state, and redaction | \~260 | | `apps/server/tests/containerRuntimeManager.test.ts` | Unit tests for Docker/Apple probe parsing, image state, mounts, network profile, cleanup posture, and unavailable fallbacks | \~240 | | `apps/server/tests/terminalContainerRoutes.test.ts` | Route tests for auth inheritance, validation, idempotency, no raw echo, terminal lifecycle, container probes, and WebSocket updates | \~280 | | `apps/web/src/lib/terminalContainers.ts` | Web view models for terminal sessions, output windows, isolation capabilities, fallback reasons, and container readiness rows | \~220 | | `apps/web/src/components/orchestration/TerminalRuntimeDrawer.tsx` | Scoped terminal drawer with lifecycle controls, bounded output, input, restart/kill states, and accessibility support | \~300 | | `apps/web/src/components/orchestration/IsolationCapabilityPanel.tsx` | Isolation/runtime capability rows for PTY, Docker, Apple Containers, image, mounts, network, browser deps, cleanup, and fallback reasons | \~240 | | `apps/web/tests/terminalContainers.test.ts` | View-model tests for safe terminal/container labels, fallback ordering, output caps, and blocked payload rejection | \~160 | | `apps/web/tests/TerminalRuntimeDrawer.test.tsx` | Component tests for drawer output, controls, loading/empty/error/offline states, focus, and duplicate-trigger guards | \~220 | | `apps/web/tests/IsolationCapabilityPanel.test.tsx` | Component tests for runtime capability rows, unavailable states, fallback reasons, and product-facing copy | \~180 | ### Files To Modify | File | Changes | Est. Lines | | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ---------- | | `packages/protocol/src/orchestrationCommandCenter.ts` | Add terminal session, terminal action, container runtime, isolated spawn, bounded output metadata, and execution attachment contracts | \~240 | | `packages/protocol/src/isolation.ts` | Upgrade isolation executor posture for terminal/container readiness, fallback reasons, cleanup, mounts, and network profile metadata | \~160 | | `packages/protocol/src/index.ts` | Export updated terminal/container/isolation contracts | \~10 | | `packages/protocol/tests/orchestrationCommandCenter.test.ts` | Cover terminal/container contracts, parsers, execution attachment metadata, and blocked raw payload fields | \~180 | | `packages/protocol/tests/isolation.test.ts` | Cover updated isolation readiness, fallback reason, cleanup, mount, and network profile contracts | \~140 | | `apps/server/package.json` | Add package-managed optional PTY adapter dependency with fail-closed runtime behavior | \~10 | | `package-lock.json` | Record package-managed dependency changes | \~80 | | `apps/server/src/managers/executorRegistry.ts` | Register terminal and container entries that probe managers and execute only when capability gates pass | \~160 | | `apps/server/src/managers/orchestrationCommandCenter.ts` | Store terminal/container execution updates, result attachments, capability refresh data, and safe event snapshots | \~140 | | `apps/server/src/lib/isolationDiagnostics.ts` | Include terminal/container readiness and fallback metadata without raw command/output/path echo | \~120 | | `apps/server/src/routes/commandCenter.ts` | Connect terminal/container execution records and probe refresh with existing command-center endpoints where needed | \~80 | | `apps/server/src/server.ts` | Instantiate managers, wire routes, pass managers into executor registry, and dispose terminal resources on shutdown | \~90 | | `apps/server/tests/executorRegistry.test.ts` | Cover terminal/container capability transitions, non-ready repair guidance, timeout, cleanup, and bounded result summaries | \~180 | | `apps/server/tests/commandCenterRoutes.test.ts` | Cover terminal/container execution run snapshots, guarded approval path, and WebSocket update frames | \~170 | | `apps/server/tests/isolationDiagnostics.test.ts` | Cover readiness metadata, unavailable fallback reasons, no raw echo, auth inheritance, and read-only diagnostics | \~160 | | `apps/web/src/lib/orchestrationApi.ts` | Add terminal/container fetch and mutation clients plus parser guards and duplicate in-flight keys | \~220 | | `apps/web/src/lib/commandCenterUi.ts` | Add terminal/container summary copy, safe run metadata, scoped output labels, fallback reason labels, and action availability | \~150 | | `apps/web/src/store/useGameStore.ts` | Normalize terminal/container snapshots and events, reconcile selected terminal state, and reset stale drawer data | \~170 | | `apps/web/src/components/orchestration/CommandCenterPanes.tsx` | Wire isolation capability panel and terminal drawer entry points into existing executor/command-center panes | \~110 | | `apps/web/src/components/orchestration/ExecutorFamiliesPanel.tsx` | Show terminal/container readiness and recent runs without broad terminal output | \~80 | | `apps/web/src/components/orchestration/OrchestrationDrawer.tsx` | Render safe terminal/container execution details and result attachments without raw broad output | \~90 | | `apps/web/src/components/orchestration/OrchestrationShell.tsx` | Wire terminal/container API actions, in-flight keys, toasts, selection, and offline states | \~140 | | `apps/web/tests/orchestrationApi.test.ts` | Cover terminal/container clients, parser failures, route ids, duplicate guards, and error mapping | \~180 | | `apps/web/tests/commandCenterStore.test.ts` | Cover terminal/container event normalization, stale drawer reset, malformed payload rejection, and no raw echo | \~160 | | `apps/web/tests/ExecutorFamiliesPanel.test.tsx` | Cover terminal/container family rows, refresh actions, unavailable/readiness states, and hidden raw output | \~140 | | `apps/web/tests/OrchestrationPanel.test.tsx` | Cover terminal drawer and isolation panel integration across loading, offline, error, and ready states | \~220 | | `docs/isolation-and-sandbox.md` | Update terminal/container threat model sections with implemented capability gates and remaining no-claim boundaries | \~160 | | `docs/api/README_api.md` | Document terminal/container routes, scoped output boundary, probe responses, and execution records | \~160 | | `apps/server/README_server.md` | Document server terminal/container manager behavior, optional PTY dependency, and local-only boundaries | \~100 | | `apps/web/README_web.md` | Document scoped terminal drawer and isolation capability panel behavior | \~80 | *** ## 7. Success Criteria ### Functional Requirements * [ ] Terminal capability probes report PTY availability, active session count, cwd label, shell label, timeout policy, output cap, cleanup posture, and fallback reason. * [ ] Approved terminal commands can create a bounded terminal session, stream scoped output, accept input, stop on timeout, be killed, be restarted, exit with status metadata, and attach a safe execution result. * [ ] Terminal broad rows and WebSocket events expose status, owner, duration, exit code, result summary, and safe labels only, while bounded output is visible only in the scoped drawer. * [ ] Container runtime probes report Docker, Apple Containers, image state, browser dependencies, auth mount, worktree mount, network/port profile, provider/runtime availability, cleanup posture, and fallback reason. * [ ] Isolated spawn is represented as a guarded lifecycle action that executes only when required probes pass and otherwise returns structured unavailable or preview-only results. * [ ] Executor registry terminal/container capabilities transition correctly between unavailable, failed, and executor-ready states based on manager probes. * [ ] Web UI renders terminal drawer and isolation rows with complete loading, empty, error, offline, unavailable, executing, killed, exited, restarted, and failed states. ### Testing Requirements * [ ] Protocol tests cover terminal/container contracts, isolation readiness metadata, parser behavior, and blocked raw payload fields. * [ ] Server manager tests cover PTY adapter probing, output caps, timeouts, input, kill, restart, cleanup, Docker/Apple probes, image/mount/network readiness, and fallback reasons. * [ ] Route and executor tests cover auth inheritance, validation, idempotency, guarded approval, capability refresh, WebSocket frames, and no raw echo. * [ ] Web API, store, view-model, and component tests cover terminal/container snapshots, malformed payloads, duplicate-trigger guards, offline/error states, and scoped output rendering. * [ ] Runtime verification scenarios are recorded for missing PTY, missing Docker, ready probe mocks, killed terminal, timed-out terminal, unavailable isolated spawn, and successful mocked isolated spawn. ### Non-Functional Requirements * [ ] Raw command bodies, raw terminal output, full cwd, env values, broad paths, tokens, secrets, transcripts, logs, state files, Worker payloads, and hosted account data are not emitted in broad route responses, WebSocket snapshots, diagnostics, logs, exports, replay, or docs examples. * [ ] Terminal output buffers are bounded, truncated deterministically, and cleaned up on session exit, kill, restart, timeout, server shutdown, and drawer re-entry. * [ ] Terminal/container mutations use idempotency keys, in-flight locks, stale-revision checks where applicable, timeout handling, and explicit error mapping. * [ ] Capability refresh and diagnostics remain read-only and do not run terminal or container actions. * [ ] UI controls have accessible names, visible focus states, keyboard support, and product-facing copy only. ### Quality Gates * [ ] All files ASCII-encoded * [ ] Unix LF line endings * [ ] Code follows project conventions * [ ] Primary user-facing surfaces contain product-facing copy only * [ ] Focused protocol, server, and web tests pass * [ ] Workspace typecheck passes * [ ] Root format check and lint pass *** ## 8. Implementation Notes ### Working Assumptions * Cross-package session scope: The analysis script reports the candidate package as `null`, while the stub names `apps/server` and `apps/web`; planning can proceed with `Package: null` because protocol, server, web, docs, and package metadata all need coordinated changes. * Optional runtime dependencies are acceptable when fail-closed: `apps/server/package.json` currently has no PTY dependency, so the implementation should add a package-managed optional PTY adapter and keep terminal capability unavailable when it is absent or fails to load. * Docker and Apple Containers are probes, not prerequisites: planning can proceed because tests can use injectable command runners and real local runtimes can report unavailable fallback reasons. * Protocol updates are required: current command-center and isolation contracts contain generic terminal/container family names but not the session, output-cap, probe, mount, network, cleanup, or fallback metadata required by the Session 12 stub. ### Conflict Resolutions * The current `docs/isolation-and-sandbox.md` says terminal and container executors are unavailable, while the Phase 19 stub says this session adds owned capabilities. The chosen interpretation is to update the threat model and implementation together: only terminal/container paths that satisfy capability, permission, audit, redaction, timeout, cleanup, and test gates become executable; all missing gates stay structured unavailable. * The Phase 19 stub says terminal output is in scope, while PRD carry-forward blocks broad terminal output exposure. The chosen interpretation is scoped output only: the terminal drawer may show bounded output after explicit selection, while broad rows, diagnostics, WebSocket summaries, exports, replay, Worker transfer, and docs examples never include raw terminal output. * The stub references isolated spawn, while remote and hosted execution remain out of scope. The chosen interpretation is local container isolation only when Docker or Apple Containers probes pass; remote tunnels, hosted queues, and Worker command bridges remain excluded. ### Key Considerations * Terminal command request bodies may be needed to run a local action, but they must remain request-scoped or manager-scoped and must not become persisted command-center records or broad WebSocket payloads. * Capability probes must not execute user commands. They may inspect dependency presence, version labels, counts, and readiness through bounded command runners. * Cleanup must run on terminal exit, kill, restart, timeout, route failure, manager disposal, and server shutdown. * Container probe outputs can include paths and environment details, so responses should return labels and fallback codes, not raw command output. * Existing file/git executor behavior must not regress while terminal/container entries are added. ### Potential Challenges * PTY native dependency may fail to install or load: keep dynamic import and adapter probing fail-closed with a clear unavailable reason. * Terminal commands can have side effects: require guarded approval and make rollback limitations visible before and after execution. * Output buffering can leak sensitive text: cap output, redact broad summaries, and confine raw-ish bounded output to the scoped drawer only. * Container readiness differs by platform: model Docker and Apple Containers separately and allow both to be unavailable without failing the app. * Drawer re-entry can show stale state: reset or revalidate selected terminal details on open and after socket reconnect. ### Relevant Considerations * \[P03] **Real executors remain unimplemented by design**: This session closes only terminal/container paths that satisfy threat-model, authorization, audit, redaction, tests, and docs gates. * \[P03-packages/protocol] **Protocol leads cross-package work**: Add terminal/container contracts before server and web behavior. * \[P03-apps/server] **Local server boundary must stay conservative**: New routes inherit auth, CORS, rate limits, body caps, validation, compact errors, and explicit unavailable behavior. * \[P07] **Redaction is boundary-specific**: Terminal/container summaries, diagnostics, drawer output, logs, WebSocket frames, docs, and execution records each need separate minimization. * \[P18-apps/server] **Manager-owned persistence and snapshot emission**: Keep runtime state and broadcasts behind manager boundaries so cleanup and filtering stay aligned. * \[P18-apps/web] **Pure normalization before store mutation**: Normalize terminal/container payloads before updating Zustand. ### Behavioral Quality Focus Checklist active: Yes Top behavioral risks for this session: * Terminal or container actions could execute twice without in-flight and idempotency protection. * PTY sessions, timeouts, or container probes could leak resources without cleanup on scope exit for all acquired resources. * Broad route responses or WebSocket frames could expose raw command bodies, terminal output, env values, paths, tokens, or logs. * Missing PTY, Docker, Apple Containers, image state, or mount prerequisites could blank the UI instead of rendering structured unavailable states. * Drawer re-entry or reconnect could show stale terminal output without revalidation. *** ## 9. Testing Strategy ### Unit Tests * Protocol parser tests for terminal session records, terminal lifecycle actions, container runtime probes, isolation fallback reasons, execution attachments, and blocked raw payload fields. * Server terminal manager tests with fake PTY adapters for probe success/failure, output cap truncation, timeout cleanup, stdin, kill, restart, exit code, result attachment, and redacted summaries. * Server container manager tests with fake command runners for Docker unavailable, Docker ready, Apple Containers unavailable, image missing, browser dependency missing, mount unavailable, network profile invalid, cleanup failure, and isolated spawn preview. * Web helper tests for terminal session cards, bounded output labels, fallback ordering, isolation rows, and blocked payload rejection. ### Integration Tests * REST route tests for terminal snapshots, terminal preview/run/input/kill/restart, container probes, isolated spawn preview, auth inheritance, invalid payloads, idempotency, and no raw echo. * Executor registry tests for terminal/container capability readiness, approved run execution, non-ready repair guidance, timeout, cleanup failure, and bounded result summaries. * Command-center route and WebSocket tests for terminal/container execution snapshots, capability refresh, event counts, and malformed payload handling. * Web API, store, and component tests for terminal/container route clients, in-flight duplicate guards, drawer lifecycle, isolation panel states, offline/error states, and product-facing copy. ### Runtime Verification * Probe with no PTY dependency and confirm terminal capability is unavailable with a safe fallback reason. * Probe with mocked ready PTY adapter and confirm terminal command approval creates a running session and bounded execution run. * Kill a running mocked terminal and confirm cleanup, state update, and result attachment. * Timeout a mocked terminal and confirm failure state, cleanup, and no duplicate run on retry. * Probe with no Docker or Apple Containers and confirm isolation panel remains readable. * Probe with mocked Docker ready state and confirm isolated spawn preview/run produces only safe labels and execution metadata. ### Edge Cases * Missing PTY adapter * PTY adapter throws during probe * PTY exits before input * Terminal input after exit * Kill after already killed * Restart after failed start * Command timeout * Oversized terminal output * Raw command body in broad event payload * Env value containing token-like text * Docker CLI missing * Apple Containers CLI missing * Image not present * Worktree mount unavailable * Auth mount unavailable * Network or port profile invalid * Cleanup failure after execution * Duplicate idempotency key * Stale or missing guarded action revision * Reopened terminal drawer after reconnect *** ## 10. Dependencies ### Other Sessions * Depends on: `phase19-session03-web-shell-and-store`, `phase19-session05-attention-and-permissions`, `phase19-session06-executor-registry`, `phase19-session07-provider-diagnostics`, `phase19-session08-file-and-git`, `phase19-session09-heroes-and-lineage` * Depended by: `phase19-session13-collaboration-and-handoff`, `phase19-session14-channels-and-scope`, `phase19-session15-metrics-and-notifications`, `phase19-session16-ergonomics-and-documentation` *** ## Next Steps Run the `implement` workflow step to begin implementation. --- # 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/phase19-session12-terminal-and-containers/spec.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.