# fleets/actions
Documentation: next (source: develop).

Install the preview: `pnpm add @aephia/atlas-kit@next`. These docs follow develop and may include changes not yet published to npm.

Markdown source of https://develop.atlas-kit-docs.pages.dev/reference/fleets/actions/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

## Interfaces

<a id="planaddshiptofleetoptions"></a>

### PlanAddShipToFleetOptions

Defined in: [packages/sage/src/fleets/actions/add-ship.ts:24](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/add-ship.ts#L24)

Explicit address-only selection of escrowed ships for an owned Docked Fleet.

#### Example

```ts
declare const profile: Address, authority: Address;
const options: PlanAddShipToFleetOptions = {authorization:{profile,authority,keyIndex:0},shipId:1,amount:1n};
```

#### Properties

<a id="amount"></a>

##### amount

```ts
readonly amount: bigint;
```

Defined in: [packages/sage/src/fleets/actions/add-ship.ts:27](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/add-ship.ts#L27)

<a id="authorization"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/add-ship.ts:25](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/add-ship.ts#L25)

<a id="shipid"></a>

##### shipId

```ts
readonly shipId: number;
```

Defined in: [packages/sage/src/fleets/actions/add-ship.ts:26](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/add-ship.ts#L26)

***

<a id="plancreatefleetoptions"></a>

### PlanCreateFleetOptions

Defined in: [packages/sage/src/fleets/actions/create-fleet.ts:24](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/create-fleet.ts#L24)

Address-only options for creating an empty Fleet at an existing own-faction StarbasePlayer.

#### Example

```ts
declare const profile:Address, authority:Address, system:Address;
const options:PlanCreateFleetOptions={authorization:{profile,authority,keyIndex:0},system,label:'Scout'};
```

#### Properties

<a id="authorization-1"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/create-fleet.ts:25](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/create-fleet.ts#L25)

<a id="label"></a>

##### label

```ts
readonly label: string;
```

Defined in: [packages/sage/src/fleets/actions/create-fleet.ts:27](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/create-fleet.ts#L27)

<a id="system"></a>

##### system

```ts
readonly system: Address;
```

Defined in: [packages/sage/src/fleets/actions/create-fleet.ts:26](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/create-fleet.ts#L26)

***

<a id="plandepositshipstogameoptions"></a>

### PlanDepositShipsToGameOptions

Defined in: [packages/sage/src/fleets/actions/ship-import.ts:61](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/ship-import.ts#L61)

Exact whole ships to import under one explicit configuration ID.
Optional escrow creation requires an explicit payer; it never registers onboarding accounts.

#### Example

```ts
declare const owner: Address;
declare const authorization: PlanAuthorization;
const options: PlanDepositShipsToGameOptions = { shipId: 1, amount: 2n, owner, authorization };
```

#### Properties

<a id="amount-1"></a>

##### amount

```ts
readonly amount: bigint;
```

Defined in: [packages/sage/src/fleets/actions/ship-import.ts:63](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/ship-import.ts#L63)

<a id="authorization-2"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/ship-import.ts:65](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/ship-import.ts#L65)

<a id="escrowaccount"></a>

##### escrowAccount?

```ts
readonly optional escrowAccount?: {
  mode: "create-if-missing";
  payer: Address;
};
```

Defined in: [packages/sage/src/fleets/actions/ship-import.ts:67](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/ship-import.ts#L67)

###### mode

```ts
readonly mode: "create-if-missing";
```

###### payer

```ts
readonly payer: Address;
```

<a id="owner"></a>

##### owner

```ts
readonly owner: Address;
```

Defined in: [packages/sage/src/fleets/actions/ship-import.ts:64](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/ship-import.ts#L64)

<a id="shipid-1"></a>

##### shipId

```ts
readonly shipId: number;
```

Defined in: [packages/sage/src/fleets/actions/ship-import.ts:62](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/ship-import.ts#L62)

<a id="source"></a>

##### source?

```ts
readonly optional source?: Address;
```

Defined in: [packages/sage/src/fleets/actions/ship-import.ts:66](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/ship-import.ts#L66)

***

<a id="planfleetcrewtransferoptions"></a>

### PlanFleetCrewTransferOptions

Defined in: [packages/sage/src/fleets/actions/crew-transfer.ts:18](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/crew-transfer.ts#L18)

Direct player authorization and the positive count for ordinary Docked Fleet crew transfer.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetCrewTransferOptions = { authorization, count: 1 };
```

#### Properties

<a id="authorization-3"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/crew-transfer.ts:19](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/crew-transfer.ts#L19)

<a id="count"></a>

##### count

```ts
readonly count: number;
```

Defined in: [packages/sage/src/fleets/actions/crew-transfer.ts:20](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/crew-transfer.ts#L20)

***

<a id="planfleetdockoptions"></a>

### PlanFleetDockOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:123](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L123)

Inputs for planning one idle-to-docked Fleet transition.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetDockOptions = { authorization };
```

#### Properties

<a id="authorization-4"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:124](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L124)

***

<a id="planfleetrespawnoptions"></a>

### PlanFleetRespawnOptions

Defined in: [packages/sage/src/fleets/actions/respawn.ts:17](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/respawn.ts#L17)

Direct player authorization and the faction CSS System for explicit timed recovery.

#### Example

```ts
declare const authorization: PlanAuthorization, system: Address;
const options: PlanFleetRespawnOptions = { authorization, system };
```

#### Properties

<a id="authorization-5"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/respawn.ts:18](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/respawn.ts#L18)

<a id="system-1"></a>

##### system

```ts
readonly system: Address;
```

Defined in: [packages/sage/src/fleets/actions/respawn.ts:19](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/respawn.ts#L19)

***

<a id="planfleetsettlearrivaloptions"></a>

### PlanFleetSettleArrivalOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:192](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L192)

Explicit authority for a completed Fleet journey, separate from the fee payer.

Requires direct Profile authorization for current Game subwarp.
Certificates are not supported for arrival.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetSettleArrivalOptions = { authorization };
```

#### Properties

<a id="authorization-6"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:193](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L193)

***

<a id="planfleetstopsubwarpoptions"></a>

### PlanFleetStopSubwarpOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:204](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L204)

Inputs for stopping one Fleet subwarp early.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetStopSubwarpOptions = { authorization };
```

#### Properties

<a id="authorization-7"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:205](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L205)

***

<a id="planfleetundockoptions"></a>

### PlanFleetUndockOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:111](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L111)

Inputs for planning one docked-to-idle Fleet transition.

#### Example

```ts
declare const authorization: PlanAuthorization;
const options: PlanFleetUndockOptions = { authorization };
```

#### Properties

<a id="authorization-8"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:112](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L112)

***

<a id="planfleetwarplaneoptions"></a>

### PlanFleetWarpLaneOptions

Defined in: [packages/sage/src/fleets/actions/index.ts:176](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L176)

Inputs for planning one explicit connected-system Fleet warp.

#### Example

```ts
declare const authorization: PlanAuthorization;
declare const destinationSystem: Address;
const options: PlanFleetWarpLaneOptions = {
  authorization,
  destinationSystem,
};
```

#### Properties

<a id="authorization-9"></a>

##### authorization

```ts
readonly authorization: PlanAuthorization;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:177](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L177)

<a id="destinationsystem"></a>

##### destinationSystem

```ts
readonly destinationSystem: Address;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:178](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L178)

## Type Aliases

<a id="fleetdockdebitbounds"></a>

### FleetDockDebitBounds

```ts
type FleetDockDebitBounds = 
  | {
  reason:   | DockBoundsUnavailableReason
     | "not-fleet-dock"
     | "multiple-fleet-docks"
     | "combined-plan";
  status: "unavailable";
  toJSON: unknown;
}
  | {
  fleet: Address;
  maximumFleetGrowthBytes: 40;
  maximumProfileDebit: bigint;
  profile: Address;
  profileUnit: "lamports";
  starbasePlayer: Address;
  status: "available";
  transactionFees: "excluded";
  toJSON: unknown;
};
```

Defined in: [packages/sage/src/fleets/actions/dock-bounds.ts:19](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/dock-bounds.ts#L19)

Conservative gross Profile storage debit for qualified ordinary docking.
Surplus and refunds are not credited; unavailable never implies zero cost.

#### Example

```ts
declare const bounds: FleetDockDebitBounds;
if (bounds.status === 'available') console.log(bounds.maximumProfileDebit);
```

***

<a id="planfleetcoordinatemovementoptions"></a>

### PlanFleetCoordinateMovementOptions

```ts
type PlanFleetCoordinateMovementOptions = 
  | {
  authorization: PlanAuthorization;
  destination: FleetSnapshot["location"];
  destinationRaw?: never;
}
  | {
  authorization: PlanAuthorization;
  destination?: never;
  destinationRaw: {
     x: bigint;
     y: bigint;
  };
};
```

Defined in: [packages/sage/src/fleets/actions/index.ts:149](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L149)

Inputs for planning one explicit coordinate-destination Fleet movement.

Choose exactly one representation. `destination` accepts display numbers and
applies the generated I8F56 codec's rounding. `destinationRaw` preserves an
exact signed-I8F56 value, such as a Star System's `coordinatesRaw`.

#### Example

```ts
declare const authorization: PlanAuthorization;
declare const destinationSystem: {
  readonly coordinatesRaw: { readonly x: bigint; readonly y: bigint };
};
const displayOptions: PlanFleetCoordinateMovementOptions = {
  authorization,
  destination: { x: 12, y: -7 },
};
const exactOptions: PlanFleetCoordinateMovementOptions = {
  authorization,
  destinationRaw: destinationSystem.coordinatesRaw,
};
```

## Functions

<a id="getfleetdockdebitbounds"></a>

### getFleetDockDebitBounds()

```ts
function getFleetDockDebitBounds(plan): FleetDockDebitBounds;
```

Defined in: [packages/sage/src/fleets/actions/dock-bounds.ts:51](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/dock-bounds.ts#L51)

Inspects the persisted docking ceiling without network I/O. Inspect individual
Plans before combining distinct Fleets. Fresh pre-sign checks are not an atomic
on-chain spending cap; state can change before landing.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `plan` | [`Plan`](/reference/planning/#plan) |

#### Returns

[`FleetDockDebitBounds`](/reference/fleets/actions/#fleetdockdebitbounds)

#### Example

```ts
declare const plan: Plan;
const bounds = getFleetDockDebitBounds(plan);
if (bounds.status === 'available') console.log(bounds.maximumProfileDebit);
```

***

<a id="planaddshiptofleet"></a>

### planAddShipToFleet()

```ts
function planAddShipToFleet(
   ctx, 
   fleet, 
input): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/add-ship.ts:88](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/add-ship.ts#L88)

Plans one singleton transfer of an exact ship configuration from StarbasePlayer entitlement to an owned Docked Fleet.
Follows the program's assembly rules for ships of any size: each ship must be
within the Character's maximum ship size and its research tags must all be
held; the resulting Fleet's points (XXS 1, XS 4, Small 9, Medium 16, Large 25,
Capital 36, Commander 49, Titan 128) must fit both the Character's Fleet size
and the Game limit, with at most one Titan and two Commanders and Titans
together. Escrowed hulls of any configuration of the same ship count, as the
program re-tags them. Any Starbase with a current StarbasePlayer of the
Fleet's faction works. Configurations that need ship components, and Fleets
built under older ship definitions, are not planned yet.
The explicit ship ID must be a u16 and the whole ship amount must be 1n through 255n. Uses a direct Profile
AUTH key or a manageFleet key scoped to SAGE or the Fleet; a positive Profile
rent shortfall additionally requires vault-funding permission. No token
transfer or onboarding occurs.
A rented Fleet is refused, as is a Fleet whose HP plus pending repair cannot
reach its maximum; the program also needs full AP and SP, which recover on
timers and stay chain-authoritative.
Final stats, research, refresh and outcomes remain chain-authoritative.
Simulate before signing. The observed debit ceiling is rechecked before
signing and is not an atomic on-chain spending cap. Two assembly Plans for the same Profile
cannot compose because they share funds and assembly state.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `input` | [`PlanAddShipToFleetOptions`](/reference/fleets/actions/#planaddshiptofleetoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx:SageContext, fleet:Address, profile:Address, authority:Address;
const plan = await planAddShipToFleet(ctx,fleet,{authorization:{profile,authority,keyIndex:0},shipId:1,amount:1n});
console.log(plan.describe());
```

***

<a id="plancreatefleet"></a>

### planCreateFleet()

```ts
function planCreateFleet(ctx, input): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/create-fleet.ts:69](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/create-fleet.ts#L69)

Plans a standalone empty Docked Fleet, without signing or submitting.
Derives all account addresses from the configured Game, Profile, exact label
and System. Accepted label bytes are preserved. Requires an existing own-faction
StarbasePlayer, a direct Profile AUTH or SAGE manageFleet key, and available
stored Character capacity. The Profile pays only the Fleet target's rent
shortfall; a non-AUTH key needs drainSolVault only for a positive debit.
The observed debit is checked again before signing; it is not an atomic
on-chain spending cap. Final rent and funding remain chain-authoritative.
No implicit key grants, registration or funding occurs. Final modifier refresh
and deployed eligibility remain chain-authoritative: simulate before signing.
Creation Plans for the same Character cannot be combined.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `input` | [`PlanCreateFleetOptions`](/reference/fleets/actions/#plancreatefleetoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx:SageContext, profile:Address, authority:Address, system:Address;
const plan=await planCreateFleet(ctx,{authorization:{profile,authority,keyIndex:0},system,label:'Scout'});
console.log(plan.describe());
```

***

<a id="plandepositshipstogame"></a>

### planDepositShipsToGame()

```ts
function planDepositShipsToGame(
   ctx, 
   starbase, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/ship-import.ts:189](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/ship-import.ts#L189)

Plans importing whole ship tokens into a registered player's CSS ship escrow.
Requires direct Profile AUTH and token-owner authorization. The Profile vault
funds any StarbasePlayer storage shortfall; an explicit ATA payer funds optional
escrow creation. Fees are separate. No Fleet is created and no signer is retained.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `starbase` | `ShipImportStarbaseIntent` |
| `options` | [`PlanDepositShipsToGameOptions`](/reference/fleets/actions/#plandepositshipstogameoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const starbase: import('@aephia/atlas-kit/starbases').StarbasePlayerSnapshot;
declare const options: PlanDepositShipsToGameOptions;
const plan = await planDepositShipsToGame(ctx, starbase, options);
console.log(plan.describe());
```

***

<a id="planfleetcompleterespawn"></a>

### planFleetCompleteRespawn()

```ts
function planFleetCompleteRespawn(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/respawn.ts:130](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/respawn.ts#L130)

Prepares timed completion only after the stored Respawn end time according to chain Clock.
Uses the explicit Respawn-to-Docked route; never pays to bypass the timer.
Refresh confirmed state to establish arrival at the faction CSS; simulation is not confirmation.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanFleetRespawnOptions`](/reference/fleets/actions/#planfleetrespawnoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext, fleet: Address, options: PlanFleetRespawnOptions;
const plan = await planFleetCompleteRespawn(ctx, fleet, options);
console.log(plan.describe());
```

***

<a id="planfleetdock"></a>

### planFleetDock()

```ts
function planFleetDock(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1650](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1650)

Plans one explicit Fleet dock without signing, simulation, or write RPC.

The planner accepts a loaded idle or refreshable warp Fleet snapshot,
resolves the only canonical Character, Star System at its action coordinate,
and Starbase Player internally, and returns one inspectable idle-to-docked
Plan. A subwarp snapshot is refused: the dock step refreshes the Fleet
without its Character and cannot settle a subwarp journey, so settle the
arrival or stop the subwarp first.

Docking is admitted when the Starbase Player belongs to the Starbase's
controlling faction, whatever the territory and economics settings. A
foreign Starbase Player is refused while territory access is off; foreign
docking under territory access and dynamic-faction Starbases are refused as
unsupported.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetDockOptions`](/reference/fleets/actions/#planfleetdockoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetDock(ctx, fleet, { authorization });
console.log(plan.describe());
```

***

<a id="planfleetsettlearrival"></a>

### planFleetSettleArrival()

```ts
function planFleetSettleArrival(
   ctx, 
   fleet, 
input): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1365](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1365)

Plans settlement after chain time confirms the scheduled Fleet journey duration has elapsed.

Game version 2 subwarp requires explicit direct Profile authorization and
existing reconciled Career XP accounts. Warp settlement is unsupported.
Journeys whose scheduled duration has not elapsed and Idle Fleets fail locally.
Planning and execution read fresh accounts; no host clock is used.

Settlement does not guarantee reaching the destination: insufficient Fuel can
leave the Fleet Idle short of it. Low Fuel produces a planning-time warning,
not a rejection. Inspect refreshed state and location after confirmation.
Subwarp settles fuel and XP and may refund released storage rent to the
Profile. Warp cooldown remains independent. Fresh checks cannot prevent a
concurrent transaction from starting another journey before execution; the
authorized instruction could stop that new journey. Intentional early
stopping remains the separate [planFleetStopSubwarp](/reference/fleets/actions/#planfleetstopsubwarp) operation.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `input` | [`PlanFleetSettleArrivalOptions`](/reference/fleets/actions/#planfleetsettlearrivaloptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetSettleArrival(ctx, fleet, { authorization });
console.log(plan.describe());
```

***

<a id="planfleetstartrespawn"></a>

### planFleetStartRespawn()

```ts
function planFleetStartRespawn(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/respawn.ts:113](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/respawn.ts#L113)

Prepares explicit timed recovery for an owned Idle Fleet, including a zero-Fuel Fleet.
Requires Character ATLAS for the current hull recovery fees. Never deposits funds,
signs, submits, waits or automatically falls back from movement. Recovery may lose assets.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanFleetRespawnOptions`](/reference/fleets/actions/#planfleetrespawnoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext, fleet: Address, options: PlanFleetRespawnOptions;
const plan = await planFleetStartRespawn(ctx, fleet, options);
console.log(plan.describe());
```

***

<a id="planfleetstopsubwarp"></a>

### planFleetStopSubwarp()

```ts
function planFleetStopSubwarp(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1434](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1434)

Plans an early Fleet subwarp stop without signing, simulation, or write RPC.

This operation stops an in-progress subwarp before arrival. Use
[planFleetSettleArrival](/reference/fleets/actions/#planfleetsettlearrival) for a trip already known to have completed;
callers should not deliberately stop a completed trip. An idle Fleet is
still accepted so the program's benign no-op handles the normal race where
subwarp completes between planning and execution.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetStopSubwarpOptions`](/reference/fleets/actions/#planfleetstopsubwarpoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetStopSubwarp(ctx, fleet, { authorization });
console.log(plan.describe());
```

***

<a id="planfleetsubwarp"></a>

### planFleetSubwarp()

```ts
function planFleetSubwarp(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1307](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1307)

Plans one explicit Fleet subwarp to a display or exact raw coordinate without movement estimates.

A coordinate outside every Region is deep space and carries no Region hint.
A player Fleet may cross deep space, but stopping there needs the Character's
High Risk zone access; NPC Fleets need none.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetCoordinateMovementOptions`](/reference/fleets/actions/#planfleetcoordinatemovementoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetSubwarp(ctx, fleet, {
  authorization,
  destinationRaw: { x: 12n << 56n, y: -(7n << 56n) },
});
```

***

<a id="planfleetundock"></a>

### planFleetUndock()

```ts
function planFleetUndock(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1515](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1515)

Plans one explicit Fleet undock without signing, simulation, or write RPC.

The planner accepts a loaded Fleet snapshot, resolves its canonical Character,
docked Star System, and Starbase Player internally, and returns one inspectable
docked-to-idle Plan.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetUndockOptions`](/reference/fleets/actions/#planfleetundockoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetUndock(ctx, fleet, { authorization });
console.log(plan.describe());
```

***

<a id="planfleetwarplane"></a>

### planFleetWarpLane()

```ts
function planFleetWarpLane(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1193](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1193)

Plans one explicit connected-system Fleet warp without local economics estimates.

The planner resolves the source Star System from the Fleet's action coordinate,
proves connectivity from that System's decoded connections, and resolves all
generated instruction accounts internally. CurrencyCache shared accounting may
change; canonical identity/layout and the existing toll-input guards remain
checked before signing. Refresh and recreate older Plans to use this guard.

Connectivity does not guarantee eligibility. The program remains authoritative
for faction-relationship and destination-risk checks and any ATLAS toll.
Tested current PTR routes succeed with empty Fuel tanks. This planner does
not estimate lane costs or treat enabled cross-faction economics as blanket
permission.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetWarpLaneOptions`](/reference/fleets/actions/#planfleetwarplaneoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const destinationSystem: Address;
declare const authorization: PlanAuthorization;
const plan = await planFleetWarpLane(ctx, fleet, {
  authorization,
  destinationSystem,
});
```

***

<a id="planfleetwarptocoordinate"></a>

### planFleetWarpToCoordinate()

```ts
function planFleetWarpToCoordinate(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/index.ts:1332](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/index.ts#L1332)

Plans one explicit Fleet coordinate warp to a display or exact raw coordinate without movement estimates.

A coordinate outside every Region is deep space and carries no Region hint.
A player Fleet may cross deep space, but stopping there needs the Character's
High Risk zone access; NPC Fleets need none.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | [`FleetSnapshot`](/reference/fleets/#fleetsnapshot) |
| `options` | [`PlanFleetCoordinateMovementOptions`](/reference/fleets/actions/#planfleetcoordinatemovementoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext;
declare const fleet: FleetSnapshot;
declare const authorization: PlanAuthorization;
const plan = await planFleetWarpToCoordinate(ctx, fleet, {
  authorization,
  destinationRaw: { x: 12n << 56n, y: -(7n << 56n) },
});
```

***

<a id="planloadfleetcrew"></a>

### planLoadFleetCrew()

```ts
function planLoadFleetCrew(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/crew-transfer.ts:115](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/crew-transfer.ts#L115)

Loads an explicit positive u16 crew count from the canonical StarbasePlayer into a directly owned Docked Fleet.
Requires a direct Profile key with AUTH, or with the SAGE manage-crew
permission scoped to SAGE or this Fleet; current ship definitions; no
Character roster; and an absent or exact-neutral Fleet binding. Rented crew are unsupported.
Available Starbase crew exclude busy crew; capacity includes required crew and passengers.
Planning never signs or submits. This transfer must execute alone.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanFleetCrewTransferOptions`](/reference/fleets/actions/#planfleetcrewtransferoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext, fleet: Address, authorization: PlanAuthorization;
const plan = await planLoadFleetCrew(ctx, fleet, { authorization, count: 1 });
console.log(plan.describe());
```

***

<a id="planunloadfleetcrew"></a>

### planUnloadFleetCrew()

```ts
function planUnloadFleetCrew(
   ctx, 
   fleet, 
options): Promise<Plan>;
```

Defined in: [packages/sage/src/fleets/actions/crew-transfer.ts:133](https://github.com/Aephia/atlas-kit/blob/develop/packages/sage/src/fleets/actions/crew-transfer.ts#L133)

Unloads an explicit positive u16 crew count from a directly owned Docked Fleet into its canonical StarbasePlayer.
Unloading every crew member is allowed while Docked; departure requires reloading required crew.
Supports the same ordinary-crew and direct-key boundary as loading. Execute separately
and refresh after confirmation before preparing another transfer or movement.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `ctx` | [`SageContext`](/reference/#sagecontext) |
| `fleet` | `Address` |
| `options` | [`PlanFleetCrewTransferOptions`](/reference/fleets/actions/#planfleetcrewtransferoptions) |

#### Returns

`Promise`\<[`Plan`](/reference/planning/#plan)\>

#### Example

```ts
declare const ctx: SageContext, fleet: Address, authorization: PlanAuthorization;
const plan = await planUnloadFleetCrew(ctx, fleet, { authorization, count: 1 });
console.log(plan.describe());
```

## References

<a id="planauthorization"></a>

### PlanAuthorization

Re-exports [PlanAuthorization](/reference/cargo/actions/#planauthorization)