# How Atlas Kit changes the game
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.

> Five rules that make every write explicit, inspectable, and yours to sign.

Markdown source of https://develop.atlas-kit-docs.pages.dev/start-here/how-it-acts/ — see https://develop.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

[How Atlas Kit reads the game](/start-here/how-it-thinks/) covers the safe
half: reading never changes anything. This page is its counterpart for the
calls that do — moving a fleet, transferring cargo, placing a market order.
Five rules govern every one of them. Read this once before your first write;
every guide that plans an action assumes it.

## One prerequisite: a write transport

The client from [your first read](/start-here/first-read/) was created with
only a read connection. Planning works with that alone, but rehearsing and
executing need a connection that can also submit — passed explicitly as
`writeRpc`, and it can be the same endpoint:

```ts
import { createSolanaRpc } from '@solana/kit';
import { createSageClient } from '@aephia/atlas-kit';

const rpc = createSolanaRpc('https://testnet-rpc.z.ink');
const sage = createSageClient({ cluster: 'zink-ptr', rpc, writeRpc: rpc });
const ctx = sage.context;
```

Leaving `writeRpc` out is itself a safety boundary: a context without one can
never submit anything, and a rehearsal or execution attempted against it fails
with a typed `MISSING_WRITE_TRANSPORT` error instead of quietly picking a
transport for you. The snippets below assume a context created as above.

## 1. Nothing happens until you say so

Every change starts with a **Plan**. A planner reads current game state,
validates what it can prove, and returns a Plan object describing exactly one
transaction. Creating a Plan sends nothing, signs nothing, and costs nothing —
it is still just reading.

```ts
import type { PlanAuthorization } from '@aephia/atlas-kit/fleets/actions';
import { planFleetUndock } from '@aephia/atlas-kit/fleets/actions';

const authorization = {
  profile: fleet.ownerProfile.address,
  authority: walletAddress,
  keyIndex: 0,
} satisfies PlanAuthorization;

const plan = await planFleetUndock(ctx, fleet, { authorization });
console.log(plan.summary);
```

Notice the authorization is made of addresses: it names which Profile and
which of its keys will authorize the change later, without involving anything
that can sign. One Plan is one transaction, always. There is no call that
quietly performs several changes, chooses a route for you, or retries
something on your behalf. If a task needs several transactions, that is a
sequence of Plans — rule 5.

## 2. Every Plan can be read before anyone signs

A Plan describes itself in game language:

```ts
import type { PlanAuthorization } from '@aephia/atlas-kit/fleets/actions';
import { planFleetUndock } from '@aephia/atlas-kit/fleets/actions';

const authorization = {
  profile: fleet.ownerProfile.address,
  authority: walletAddress,
  keyIndex: 0,
} satisfies PlanAuthorization;

const plan = await planFleetUndock(ctx, fleet, { authorization });
console.table(plan.describe());
```

`describe()` returns stable, human-readable steps. Show them to the person who
is about to sign, every time — approval of an idea is not approval of a
transaction. If game state has changed since the Plan was created, make a new
Plan rather than repairing the old one.

## 3. You can rehearse without a wallet

`simulatePlan` runs the unsigned transaction against the realm and reports
what would happen — logs, compute cost, errors — without ever touching a
signer:

```ts
import type { PlanAuthorization } from '@aephia/atlas-kit/fleets/actions';
import { planFleetUndock } from '@aephia/atlas-kit/fleets/actions';
import { simulatePlan } from '@aephia/atlas-kit/planning';

const authorization = {
  profile: fleet.ownerProfile.address,
  authority: walletAddress,
  keyIndex: 0,
} satisfies PlanAuthorization;

const plan = await planFleetUndock(ctx, fleet, { authorization });
const rehearsal = await simulatePlan(ctx, plan, { feePayer: walletAddress });
console.log(rehearsal.unitsConsumed, rehearsal.logs.length);
```

The fee payer here is just an address, like the authority in the Plan —
nothing on this page can sign, so no wallet opens and nothing is charged.
A failed simulation is a typed error with the realm's own logs attached, which
is a far better place to discover a problem than after signing.

## 4. Your keys stay yours

The Kit is non-custodial. It never asks for a seed phrase, never stores a
key, and never signs on its own. At the moment of execution it receives a
standard signer interface from _your_ wallet integration, uses it for exactly
one transaction, and holds no reference afterwards. Which wallet, and how the
signing prompt looks, is your application's decision — the SDK only defines
the boundary.

That boundary is also why planning and signing are separate moments: everything
before the signer is safe to run anywhere, including in a browser tab that has
no wallet at all.

## 5. Execution happens once, then you read again

`executePlan` checks that the supplied signer matches the Plan, verifies the
Plan is still fresh, submits exactly once, and waits for a terminal result.
Every executed transaction costs real fees, so nothing is resubmitted quietly.

- A **confirmed** result means the change happened. Read the affected state
  again — the next ordinary read is fresh.
- An **unknown** result means submission could not be confirmed either way. Do
  not retry. Check wallet and chain history first; retrying an unknown outcome
  is how a fleet gets moved twice.

The full sign-and-execute flow, with code, is in
[Warp & subwarp](/guides/moving-a-fleet/#sign-and-execute-once) — the same
flow applies to every Plan in the SDK.

For a journey that needs several confirmed transactions — move, wait, move
again — use a [Plan sequence](/guides/plan-sequences/). It keeps each step a
single transaction, checkpoints progress in storage you own, and requires
fresh authorization for every reached step.

## Where writes live

Write planning lives in the guide for the concept it changes, next to the
reads it depends on:

- [Warp & subwarp](/guides/moving-a-fleet/) — moving a fleet
- [Cargo](/guides/cargo/#moving-cargo) — transferring cargo
- [Starbases](/guides/starbases/#registering-at-a-starbase) — registering at a starbase
- [Crafting](/guides/crafting/#running-a-process) — starting, completing, and cancelling a process
- [Markets](/guides/markets/#placing-an-order) — placing a local market order
- [Claim stakes](/guides/claim-stakes/#placing-a-claim-stake) — placing a Claim Stake and its bundled hub
- [Plans](/guides/plan-sequences/) — chaining transactions into a journey