> For the complete documentation index, see [llms.txt](https://docs.gxc.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gxc.io/docs/application-notes/5g-ap-deployment-modes.md). # 5G AP Deployment Modes ## Introduction Private cellular networks often require coverage expansion as facilities grow, production areas are reconfigured, or new operational areas are added. Traditionally, extending coverage requires deploying additional Access Points (APs), increasing infrastructure costs, cabling requirements, configuration complexity, and ongoing operational management. Multi-Port Attach is a dual-sector coverage feature that enables a single AP to serve two distinct or geographically separated operational areas. By partitioning a supported 4×4 AP into two independent 2×2 MIMO sectors, operators can independently direct high-gain, narrow-beam antennas toward different coverage areas while continuing to use a single AP. Each sector operates independently with its own 2×2 MIMO configuration, preserving the spatial diversity and antenna gain required to deliver optimal RF performance within its intended coverage area. This approach is especially valuable in uplink-heavy use cases, where a strong link budget from each sector is critical to reliable performance, without compromising uplink strength to gain coverage. Although the physical RF implementation changes, the deployment continues to operate as a single AP and a single NR Cell, preserving the existing logical network architecture. {% hint style="info" %} **NOTE:** Enabling Multi-Port Attach partitions the AP's 4×4 array into two independent 2×2 sectors, so each sector no longer has 4×4 MIMO in the downlink. This reduces the maximum downlink throughput available per sector compared to a single full-array (4×4) deployment. This is a deliberate design trade-off made in favor of extended coverage reach rather than capacity. {% endhint %} ### Key Benefits Multi-Port Attach provides the following operational and deployment benefits: * Operational Benefits: * Reduces the number of APs required to cover a facility. * Reduces infrastructure, installation, and maintenance costs. * Simplifies network management by preserving existing operational workflows. * RF Coverage Benefits: * Improves directional RF coverage for geographically separated operational areas. * Maximizes spectrum efficiency by allowing both sectors to share the same operating channel, eliminating the need to allocate separate channels for each coverage area. * Simplifies frequency/channel planning, since both sectors run on the same channel, only a single channel needs to be planned for the entire deployment instead of one per coverage area. * Preserves antenna gain and 2×2 MIMO operation for each sector. * Supports heavy-uplink use cases by maintaining a strong per-sector link budget instead of trading gain for broader coverage. * Mobility Benefits: * Keeps UE attached to the same logical NR Cell while moving between coverage areas, eliminating inter-sector handover signaling and associated control-plane overhead. * Maintains consistent service continuity across both coverage areas. ### Standard 4×4 versus Multi-Port Attach The following figure compares a standard 4×4 AP deployment with a Multi-Port Attach deployment, illustrating how a supported 4×4 AP can be partitioned into two independent 2×2 sectors while continuing to operate as a single AP and a single NR Cell.

Figure: Standard 4×4 Configuration versus Multi-Port Attach

### Deployment Scenarios Multi-Port Attach is intended for deployments where two physically separated operational areas can be served by a single AP while maintaining a single logical network. Typical deployment environments include: * Warehouses * Manufacturing facilities * Distribution centers * Long corridors * Transportation platforms * Outdoor yards * Mixed indoor/outdoor environments ### RF Coverage Comparison The following figures compare a standard 4×4 deployment with a Multi-Port Attach deployment and illustrate how partitioning a supported 4×4 AP into two independent 2×2 sectors improves RF coverage for two distinct or geographically separated operational areas.

Figure: Standard 4×4 Mode

In a standard deployment, all four antenna ports operate together as a single 4×4 MIMO sector, providing RF coverage through a single antenna pattern. This approach may result in reduced signal quality at the edges of geographically separated operational areas.

Figure: Multi-Port Attach Mode

In a Multi-Port Attach deployment, the AP antenna ports split into two independent 2×2 sectors. Each sector can be connected to a dedicated directional antenna to provide optimized RF coverage for its intended operational area while both sectors continue operating as part of the same NR Cell. This is the core benefit of the feature — going from one antenna to two lets you direct each sector into a different area while each sector keeps its own strong uplink budget, neither sector “splits” its uplink gain with the other. ### When to Use Multi-Port Attach Use Multi-Port Attach when: * Improving RF coverage is the primary deployment objective. * Two geographically separated operational areas can be effectively served by one supported AP. * Maintaining a single logical network architecture is preferred. * Reducing additional infrastructure without compromising RF design is desirable. ### When Multi-Port Attach Is Not Appropriate Do not use Multi-Port Attach when: * Additional network capacity is required. * Independent NR Cells are required. * RF planning indicates that additional APs are required. * The intended coverage areas cannot be effectively served by a single AP. * Unsupported hardware is deployed. ## Architecture Multi-Port Attach partitions the AP's four antenna ports into two independent 2×2 MIMO sectors, each connected to its own directional antenna system. Although the physical RF implementation changes, the deployment continues to behave as a standard single-cell network. ### Direct AP Deployment In a direct deployment, the Onyx Edge hosts a single NR Cell that is connected directly to one supported AP. When Multi-Port Attach is enabled, the AP provides two independent 2×2 MIMO sectors while the Distributed Unit (DU) continues to manage the deployment as a single NR Cell. This deployment model is well suited for environments where a single supported AP can provide RF coverage for two geographically separated operational areas while maintaining a single logical network.

Figure: Direct AP Deployment

### FHM-Managed Multi-AP Deployment In an FHM-managed deployment, the Onyx Edge hosts a single NR Cell that connects to one or more supported APs through a Fronthaul Multiplexer (FHM). When Multi-Port Attach is enabled on a supported AP, the AP partitions its antenna ports into two independent 2×2 MIMO sectors while the DU continues to manage the deployment as a single NR Cell. The FHM provides fronthaul connectivity between the Onyx Edge and the APs but does not change the logical operation of Multi-Port Attach.

Figure: FHM-Managed Deployment

### Logical Network and Physical RF Architecture Multi-Port Attach preserves the logical network architecture while modifying only the physical RF implementation. This separation enables the deployment to continue operating as a single AP and a single NR Cell. ### Antenna Resource Partitioning Multi-Port Attach partitions the four antenna ports of a supported 4×4 AP into two independent 2×2 MIMO sectors. The validated antenna port assignments are Sector A: Ports 1 and 2, and Sector B: Ports 3 and 4. Each sector maintains an independent 2×2 MIMO configuration while operating on the same carrier and within the same NR Cell. ### Single NR Cell Operation Although RF coverage is provided through two independently directed antenna sectors, Multi-Port Attach continues to operate as a single NR Cell. Both sectors: * Broadcast the same NR Cell. * Operate on the same carrier. * Share the same cell configuration. * Are managed by the same DU. * Operate through the same AP. From the UE perspective, the deployment appears as a single NR Cell throughout the coverage area. ### SAS / CBRS Support Multi-Port Attach supports both SAS-enabled and non-SAS deployments. In SAS-enabled deployments, the AP functions as the CBSD, while the SAS authorizes spectrum operation. Multi-Port Attach changes only the physical RF implementation and does not alter the relationship between the AP and the SAS. When Multi-Port Attach is enabled, each configured antenna gain generates a corresponding CBSD record. These CBSD records are registered independently with the SAS, enabling independent spectrum authorization for each antenna configuration while the deployment continues to operate as a single AP and a single NR Cell. In direct AP deployments, each configured antenna gain generates a corresponding CBSD record, which is registered with the SAS — allowing independent antenna and power management for each sector. In FHM-managed deployments, each AP generates its own CBSD records based on its configured antenna gain values, enabling independent spectrum authorization per AP and sector while maintaining a common operating channel across the deployment. For complete information about SAS deployment prerequisites, CBSD configuration, registration, spectrum grants, and operational procedures, refer to the *Onyx CBRS SAS Registration Application Note*. ## Deployment Prerequisites & Planning {% hint style="info" %} **NOTE:** This document assumes that the AP is already installed, mounted, and operating normally. For hardware installation, cabling, grounding, and antenna installation, and site preparation procedures, see [*GXC 5G Access Points*](https://docs.gxc.io/hw/5g/5g-access-points) for AP specifications sheets and hardware installation guides. {% endhint %} Successful Multi-Port Attach deployments begin with proper planning. Before enabling the feature, verify that the deployment environment, hardware, software, and RF design meet the deployment requirements. Completing these activities before making configuration changes helps reduce deployment risk and simplifies post-deployment validation. Before deploying Multi-Port Attach, complete the following planning activities.Verify Existing Deployment — Before enabling Multi-Port Attach, verify that the existing deployment is operating normally. Resolving existing issues before deployment significantly reduces implementation risk. * Verify that the Onyx Edge is operational. * Verify that the AP is online and operational. * Verify that the existing NR Cell is operational. * Resolve any existing alerts or configuration issues before proceeding. * Verify Hardware and Software Compatibility — Verify that all platform components support Multi-Port Attach before beginning deployment. * Plan RF Coverage — Multi-Port Attach is designed to improve RF coverage rather than increase network capacity. Proper RF planning is essential for achieving the intended coverage objectives. * Identify the operational areas that require RF coverage. * Verify that both areas can be effectively served by a single supported AP. * Determine antenna placement and orientation for each sector. * Ensure sufficient RF overlap where seamless UE mobility is required. * Frequency/channel planning is simplified. Both sectors operate on the same channel, so only one channel needs to be planned for the entire deployment. * Define Deployment Objectives — Clearly define the objectives before enabling Multi-Port Attach. Typical deployment objectives include: * Extending RF coverage to two geographically separated operational areas. * Improving RF coverage without deploying an additional AP. * Maintaining a single logical network architecture. * Optimizing infrastructure utilization while preserving RF performance. * CBRS Deployment Considerations — For deployments operating in CBRS spectrum: * Verify that the SAS environment has been prepared. * Complete all required SAS configuration before enabling Multi-Port Attach. * Verify that CPI requirements have been completed, if applicable. For detailed SAS prerequisites, CBSD configuration, and deployment procedures, refer to the *Onyx CBRS SAS Registration Application Note*. ### Deployment Design Considerations When designing a Multi-Port Attach deployment, consider the following recommendations. * RF Design * Perform an RF site survey before deployment. * Identify the operational areas to be served. * Select antennas appropriate for the deployment environment. * Validate antenna orientation and placement. * Ensure sufficient RF overlap where seamless UE mobility is expected. * Minimize physical obstructions that may affect signal propagation. * Platform Design * Verify that the AP supports Multi-Port Attach. * Verify compatible GXC Onyx software versions. * Confirm that the required feature licenses are installed. * Review the applicable release notes before deployment. * Coverage Planning * Align each RF sector with its intended operational area. * Validate the expected RF coverage before deployment. * Identify RF measurement locations for post-deployment verification. * Define acceptance criteria for coverage validation. Design RF coverage to meet operational requirements rather than simply extending coverage distance. Proper antenna selection, orientation, and placement are the primary factors that determine a successful Multi-Port Attach deployment. ## Feature Limitations & Considerations Review the following limitations and considerations before deploying Multi-Port Attach. Understanding these constraints helps ensure that the feature is deployed in supported environments and according to validated design practices. * Multi-Port Attach is supported only on 5G Onyx Edge (NR+Core) deployments. * Multi-Port Attach transition constraints apply to SAS-enabled deployments. Before changing the Multi-Port Attach state, remove all SAS-enabled cells from the deployment. Refer to [*Deploy Multi-Port Attach*](#deploy-multi-port-attach). * Enabling Multi-Port Attach reduces the maximum theoretical downlink throughput available to each sector. Partitioning a 4×4 RU into two independent 2×2 sectors reduces the number of available downlink spatial layers from four to two per sector. This is an intentional design trade-off that improves RF coverage flexibility rather than increasing capacity or user density. Consider this reduction during network planning. * Multi-Port Attach improves RF coverage but does not increase network capacity or support higher user density within a single coverage area. Deployments requiring additional capacity should use additional APs rather than Multi-Port Attach. {% hint style="warning" %} **CAUTION:** Sustained Maximum-Throughput Traffic **—** When Multi-Port Attach is enabled, sustained simultaneous maximum-rate UDP or TCP traffic across all active antenna ports may cause the Onyx Edge to reboot unexpectedly. This behavior occurs only when all active antenna ports are driven at maximum throughput simultaneously. Lower-bandwidth traffic, such as ICMP ping, is not affected. {% endhint %} {% hint style="info" %} **NOTE**: Physical Antenna Installation Requirements — Multi-Port Attach requires two independently oriented antenna systems, with one antenna system serving each operational area. For supported four-port APs, the validated antenna port pairing is Ports 1+2 and Ports 3+4. Port pairing Ports 1+3 and Ports 2+4 is not supported and must not be used. {% endhint %} {% hint style="info" %} **NOTE**: SAS-Enabled Deployments — Complete all SAS configuration and authorization procedures before enabling Multi-Port Attach. For SAS prerequisites, CBSD registration, spectrum grants, operational requirements, and troubleshooting, refer to the *Onyx CBRS SAS Registration Application Note*. {% endhint %} {% hint style="info" %} **NOTE:** Partial SAS Grant Behavior — When Multi-Port Attach is enabled, each antenna port registers as a separate CBSD with the SAS. If one CBSD receives a spectrum grant but the other does not, the expected behavior is that the AP does not radiate unless all associated CBSDs receive valid spectrum grants. {% endhint %} ## Configure Multi-Port Attach This section describes how to configure Multi-Port Attach. Before beginning deployment, complete the planning activities described in *Deployment Prerequisites and Planning.* The following diagram summarizes the end-to-end workflow for enabling Multi-Port Attach on an Onyx Edge, from verifying its current status through the point where the configuration diverges into a non-SAS path and a SAS-enabled path.

Figure: Multi-Port Attach Configuration Workflow

{% hint style="info" %} **NOTE**: If the deployment operates in CBRS spectrum, complete the required SAS configuration before enabling Multi-Port Attach. For SAS-specific procedures, refer to the *Onyx CBRS SAS Registration Application Note*. {% endhint %} ### View Multi-Port Attach Status Before configuring Multi-Port Attach, verify the current Multi-Port Attach status for the target Onyx Edge. **To view the Multi-Port Attach status of the target Onyx Edge (NR+Core)**: {% stepper %} {% step %} Navigate to **Equipment** > **Onyx Edge (NR+Core)** tab or **Onyx Edge** tab. {% hint style="info" %} **NOTE:** If a 5G network includes both Onyx Edge (NR+Core) and Onyx Edge (Core), the summary details for all Onyx Edge (NR+Core) configured in the network are displayed in the **Equipment** page > **Onyx Edge (NR+Core)** tab. If the network includes only Onyx Edge (NR+Core), the summary details are displayed in the **Equipment** page > **Onyx Edge** tab. {% endhint %} {% endstep %} {% step %} In the **Onyx Edge (n)** panel, click the Onyx Edge's name. The ***\*** page > **RAN** section > **Multi-Port Attach** parameter indicates the Multi-Port Attach feature's status — **True** (enabled) or **False** (disabled). * Onyx Edge with Multi-Port Attach disabled (**False**).
* In CBRS deployment, with Multi-Port Attach disabled (**False**) and SAS status **Authorized**:
* In CBRS deployment, to view the cell's CBSD details, click the **Show More** link.\ Cell details showing CBSD information for the single-antenna configuration:
{% endstep %} {% endstepper %} ### Add Cell Parameter Reference The following tables define the cell configuration parameters required when adding a new NR cell with Multi-Port Attach enabled, referenced in *Enable and Configure Multi-Port Attach*. Parameters vary by band and whether SAS is enabled for the cell.

Table: Parameters Applicable to N48 with SAS Disabled, N77, and N78 Bands

ParameterDescription
SAS EnabledClick the toggle switch to disable SAS. Default: disabled.
Name(Required) The cell's name.
BW (MHz)(Required) Click to select the cell's channel bandwidth from 10, 20, 40. Select the bandwidth appropriate for the deployment and RF design.
Freq (MHz)(Required) Click to select the cell's operating center frequency. Available frequencies depend on the selected band and system configuration.
Associated AP/FHM [Band N**]Click to select the associated AP/FHM.
PSS (for PCI)(Required) Click to select the Primary Synchronization Signal (PSS) from 0, 1, 2. The PSS contributes to the Physical Cell Identity (PCI). Configure a value that results in a unique PCI within the RF environment to minimize interference with neighboring cells.

Table: Parameters Applicable to N48 Band with SAS Enabled

ParameterDescription
SAS EnabledClick the toggle switch to enable SAS. Default: disabled.
Name(Required) The cell's name.
User ID(Required) The SAS account's user ID. This identifier is included during CBSD registration to authenticate ownership of the CBSD.
Preferred BW (MHz)(Required) Click to select the preferred channel bandwidth requested during SAS grant acquisition from 10, 20, 40. The SAS attempts to allocate spectrum matching this bandwidth, subject to spectrum availability and regulatory constraints. Default: 40 MHz.
Preferred Freq (MHz) in Priority Order(Required) Click to select one or more preferred center frequencies, listed in order of preference — highest priority first. During grant acquisition, the SAS attempts to assign the highest-priority available frequency.
Strict Freq Preference(Required) Click to specify whether the selected preferred frequencies must be strictly adhered to. Default: True. When True, grant requests are limited to the preferred frequency range (the system may fall back to a lower bandwidth at the same frequency if needed). When False, the next best frequency will be requested for the grant.
PSS (for PCI)(Required) Click to select the Primary Synchronization Signal (PSS) from 0, 1, 2. The PSS contributes to the Physical Cell Identity (PCI). Configure a value that results in a unique PCI within the RF environment to minimize interference with neighboring cells.
Access Point Association
Associated AP/FHM(Required) Click to select the AP or FHM to associate with this cell. Selecting an FHM enables unified control of SAS settings for all APs associated with that FHM.
CBSD Category(Required) Click to select the CBSD category — Category A for devices operating at a maximum of 30 dBm EIRP, Category B for devices operating at a maximum of 47 dBm EIRP. Default: A.
Antenna Gain <n> (dBi)(Required) The antenna gain in decibels relative to an isotropic radiator (dBi). Enter an integer value in the range of 0–35. Default: 0. For Multi-Port Attach deployments, configure two values — Antenna Gain 1 and Antenna Gain 2 — one per sector.
To add Antenna Gain 2, click .
{% hint style="info" %} **NOTE**: SAS-Enabled FHM Cell Behavior — When SAS is enabled for a cell associated with an FHM, only one center frequency can be selected under Preferred Freq (MHz) in Priority Order, and Strict Preference is automatically set to True and cannot be modified. If multiple frequencies were selected before associating the cell with an FHM, the first frequency in the original selection is retained as the active choice. {% endhint %} ### Enable and Configure Multi-Port Attach Multi-Port Attach is configured at the Onyx Edge level, is disabled by default, and can be enabled or disabled independently for each Onyx Edge. {% hint style="info" %} **NOTE:** You can enable or disable the Multi-Port Attach feature for an Onyx Edge only if you are a GXC Administrator, Partner Administrator, Super Administrator, or an Administrator. {% endhint %} {% hint style="info" %} **NOTE:** If the Onyx Edge contains SAS-enabled cells, you must delete those cells and save the configuration before you can enable Multi-Port Attach. See [*Update Workflow and Multi-Port Transition Constraints*](#update-workflow-and-multi-port-transition-constraints) for details. {% endhint %} **To enable and configure Multi-Port Attach for an Onyx Edge:** {% stepper %} {% step %} Navigate to **Equipment** > **Onyx Edge (NR+Core)** tab or the **Onyx Edge** tab. {% endstep %} {% step %} For the Onyx Edge that you want to configure, in the **Onyx Edge (n)** panel > **Actions** column, click the corresponding **⋮** (options) icon, then click **Edit**. The **Edit Onyx Edge (*****\*****)** page is displayed.
{% endstep %} {% step %} Click the **RAN** tab.
{% endstep %} {% step %} If the Onyx Edge contains any SAS-enabled cells, delete them before continuing: 1. For each SAS-enabled cell, click the corresponding ⋮ (options) icon, then click **Delete**.
2. Confirm the deletion when prompted. 3. Click **Save Onyx Edge** to save the configuration with the cell(s) removed. {% hint style="info" %} **NOTE:** You cannot enable Multi-Port Attach while previously configured SAS-enabled cells exist on the Onyx Edge. This save step must complete before proceeding to Step 5. {% endhint %} {% endstep %} {% step %} To enable the Multi-Port Attach feature, toggle the **Multi-Port Attach** switch on.
{% endstep %} {% step %} To add a cell, click **Add Cell**. The **Add Cell** dialog box is displayed. {% hint style="info" %} **NOTE**: The parameters displayed in the **Add Cell** dialog box depend on whether SAS is enabled or disabled. {% endhint %} **N48 band with SAS disabled, N77, and N78 bands:**
**N48 band with SAS enabled:**
{% endstep %} {% step %} Enter the required details and click **Submit**. For parameter descriptions, see [*Add Cell Parameters Reference*](#add-cell-parameters). Sample configuration screens: * SAS disabled:
* SAS enabled with two Antenna Gain configured:
{% endstep %} {% step %} To save your edits, in the top right corner of the page, click **Save Onyx Edge**. {% endstep %} {% endstepper %} #### SAS-Enabled Deployments The deployment workflow for SAS-enabled networks is the same as for non-SAS deployments, with the additional SAS configuration required before RF transmission can begin. For how CBSD records are generated and registered per sector, see [*SAS / CBRS Support*](#sas-cbrs-support). When Multi-Port Attach is enabled: * Each configured antenna gain generates a corresponding CBSD record. * Each generated CBSD is registered independently with the SAS. * Spectrum grants are managed independently for each CBSD. **Transition Constraints** When changing the Multi-Port Attach state in a SAS-enabled deployment: * Remove all SAS-enabled cells before enabling or disabling Multi-Port Attach. * Save the configuration before adding the required cells. For SAS account setup, CPI requirements, CBSD registration, spectrum grants, heartbeat procedures, and troubleshooting, refer to the *Onyx CBRS SAS Registration Application Note*. ## Verify the Deployment After deploying Multi-Port Attach, verify that the configuration has been successfully applied and that the deployment is operating as expected. Validation should begin by confirming that the configuration has been applied correctly in the Onyx Portal, followed by verification of platform health, RF coverage, UE connectivity, and, where applicable, SAS authorization. ### Verify the Configuration Immediately after saving the configuration, verify that Multi-Port Attach has been successfully applied. **To verify the Multi-Port Attach configuration:** 1. Navigate to **Equipment** > **Onyx Edge (NR+Core)** tab or the **Onyx Edge** tab. 2. In the **Onyx Edge (n)** panel, click the Onyx Edge's name. 3. In the **RAN** section, verify Multi-Port Attach status: * Multi-Port Attach enabled (**True**) with the new cell's details.
* In CBRS deployment, Multi-Port Attach enabled (**True**) with cell's SAS status **Authorized**.
* In CBRS deployment, to view the cell's CBSD details, click the **Show More** link.
Verify that: * Two CBSD records are displayed for the NR Cell (one for each 2×2 sector). * Both CBSD records show an **Authorized** SAS status. ### Verify Platform Status Confirm that: * The Onyx Edge is online. * The AP is online. * The NR Cell is operational. * No critical alerts are active or configuration errors are reported. ### Verify RF Coverage Perform RF validation within each intended coverage area. Verify that: * Sector A provides the expected RF coverage. * Sector B provides the expected RF coverage. * Signal strength meets the planned design objectives. * Sufficient RF overlap exists where seamless UE mobility is expected. Compare the measured RF coverage against the deployment objectives established during planning. ### Verify UE Connectivity Using one or more test UE, verify that devices can successfully access the network. Confirm that the UE: * Detects the NR Cell. * Successfully attaches to the network. * Receives an IP address. * Successfully exchanges user traffic. ### Verify UE Mobility Verify that UE can move between the two operational areas while remaining connected to the same NR Cell. Confirm that: * Connectivity is maintained while moving between sectors. * No service interruption occurs. * No unexpected RRC re-establishment occurs. * No UE reattachment occurs during normal mobility. ## Related Documentation * *GXC 5G AP Hardware Installation Guides* * *Onyx CBRS SAS Registration Application Note* * *5G Onyx Portal Operations Guide* ## Contact GXC To get in touch with GXC, please visit [*https://gxc.io/contact-us/*](https://gxc.io/contact-us/). --- # 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://docs.gxc.io/docs/application-notes/5g-ap-deployment-modes.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.