---
name: aephia-atlas-kit
description: Work with Star Atlas SAGE C4 game state from TypeScript using the @aephia/atlas-kit SDK. Reading covers fleets, cargo, mining, crafting, markets, claim stakes, combat, scanning, factions, loyalty, and rewards. Changing the game goes through inspectable transaction Plans, which today cover fleet movement, cargo transfer, Starbase player registration, and Crafting Process start. Use when writing code against Star Atlas SAGE, the @aephia/atlas-kit package, or the z.ink test realm.
---

# Atlas Kit

`@aephia/atlas-kit` is an unofficial `0.x` TypeScript SDK for Star Atlas SAGE C4. It
validates every account it reads - owner, discriminator, shape, and
relationships - and exposes gameplay snapshots rather than raw account layouts.
Writes are built as inert, inspectable Plans that only execute when a caller
explicitly configures execution.

```bash
npm install @aephia/atlas-kit@next
```

## Getting the shape right first

These are the points where a reasonable guess produces broken code.

- **ESM only.** The package is `"type": "module"` with no CommonJS build.
  `require('@aephia/atlas-kit')` will not work.
- **Addresses are `@solana/kit` `Address` values**, which are branded strings.
  This is not `@solana/web3.js`; there is no `PublicKey` class and no
  `.toBase58()`.
- **Wallet to Profile is a search, not a calculation.** A Profile address is
  assigned at creation and nothing about the wallet predicts it, so there is no
  PDA to derive. The SDK resolves it but never scans the chain to do so - you
  choose how it searches. Either configure `discovery: { walletProfiles }` with
  an indexer or mapping you supply and use `strategy: 'provider'`, or pass
  `{ strategy: 'known-addresses', addresses }` when you already hold candidates.
  Either way the SDK validates each candidate's key list before returning it,
  and a wallet may hold zero, one, or many Profiles. This is the single most
  common place to get stuck; if you control the Profile addresses, skip it and
  call `sage.characters.forProfile(profileAddress)`.
- **Raw quantities are `bigint`.** Fields suffixed `Raw` (`quantityRaw`,
  `capacityRaw`) keep exact values. Do not cast them to `number` for arithmetic.
- **Never reach for previous-generation packages.** `@staratlas/sage`,
  `@staratlas/data-source`, broad `readAllFromRPC` scans, and ad hoc Anchor
  recipes target an older game generation. Pinned `@staratlas/dev-*` bindings
  are reachable only through `@aephia/atlas-kit/bindings`.
- **CargoPods are nested values, not addressable accounts.** Read fleet cargo
  through `fleet.inventory.get()` or `getFleetCargoInventory` from
  `@aephia/atlas-kit/cargo`.
- **Dispose the client** when you are done, so caches and subscriptions release.

## Two ways in

Use the root client for gameplay traversal, and capability entries when you want
a small bundle.

Most sessions begin with a wallet. Discovery needs a provider you supply,
because the SDK will not scan the chain on your behalf.

```ts
import { createSageClient, type Address } from '@aephia/atlas-kit';
import type {
  SageRpc,
  WalletProfileDiscoveryProvider,
} from '@aephia/atlas-kit/client';

declare const walletAddress: Address;
declare const rpc: SageRpc;
// Yours to provide: an indexer, or a mapping you maintain.
declare const walletProfiles: WalletProfileDiscoveryProvider;

const sage = createSageClient({
  cluster: 'zink-ptr',
  rpc,
  discovery: { walletProfiles },
});
try {
  const wallet = sage.wallets.get(walletAddress);
  const characters = await wallet.characters.all({ strategy: 'provider' });
  for (const character of characters) {
    const fleets = await character.fleets.all();
    console.log(
      character.address,
      fleets.map(({ name }) => name),
    );
  }
} finally {
  await sage.dispose();
}
```

With no provider configured, `strategy: 'provider'` throws and says so. Given a
Profile address already, `sage.characters.forProfile(profileAddress)` skips
discovery entirely.

## Entry points

Entry points follow gameplay capabilities, not individual accounts.

| Entry point                      | Purpose                                                                                             |
| -------------------------------- | --------------------------------------------------------------------------------------------------- |
| `@aephia/atlas-kit`                   | Loaded identity, Fleet, cargo, Claim Stake, Starbase, mining, crafting, market, and world traversal |
| `@aephia/atlas-kit/client`            | Context, cache, freshness options, subscriptions, provenance                                        |
| `@aephia/atlas-kit/identity`          | Wallets, Profiles, Characters, XP progression, Game research catalog                                |
| `@aephia/atlas-kit/world`             | Game, regions, Star Systems, Celestial Bodies, shared Starbase data                                 |
| `@aephia/atlas-kit/starbases`         | Player-local Starbase state, facilities, upgrades                                                   |
| `@aephia/atlas-kit/starbases/actions` | Address-only StarbasePlayer registration planning                                                   |
| `@aephia/atlas-kit/fleets`            | Fleets, ships, composition, movement state                                                          |
| `@aephia/atlas-kit/fleets/actions`    | Fleet undock, coordinate-movement, lane-warp, docking, arrival-settlement, and early subwarp-stop planners |
| `@aephia/atlas-kit/cargo`             | Cargo pods, inventory, capacity, resource movement                                                  |
| `@aephia/atlas-kit/cargo/actions`     | Fleet/player-Starbase and within-Fleet cargo transfer planning                                      |
| `@aephia/atlas-kit/claim-stakes`      | Claim Stake discovery, ownership, placement, harvesting                                             |
| `@aephia/atlas-kit/claim-stakes/actions` | Address-only Claim Stake placement, building-design planning, rent top-up, finalization, cancellation, and deconstruction |
| `@aephia/atlas-kit/mining`            | Deposits, fleet mining, extraction, timing, cargo outputs                                           |
| `@aephia/atlas-kit/planning`          | Inert Plans, persistence, composition, unsigned assembly                                            |
| `@aephia/atlas-kit/crafting`          | Recipes, Crafting Habs, Crafting Processes, production state                                        |
| `@aephia/atlas-kit/crafting/actions`  | Address-only Crafting Process start planning                                                        |
| `@aephia/atlas-kit/combat`            | Combat configuration, Fleet combat state, Loot, Outlaw Flags                                        |
| `@aephia/atlas-kit/combat/actions`    | Address-only combat stimulant planning for one owned Fleet                                           |
| `@aephia/atlas-kit/scanning`          | Scan patterns, cooldown and stat projections, Character scanning                                    |
| `@aephia/atlas-kit/rewards`           | ATLAS reward epochs, configuration, treasuries, Loot commitments                                    |
| `@aephia/atlas-kit/factions`          | Faction identity, economics, diplomacy, standing, territory                                         |
| `@aephia/atlas-kit/loyalty`           | Faction epochs, Profile contributions, accumulated ATLAS                                            |
| `@aephia/atlas-kit/loyalty/actions`   | Address-only full-balance Loyalty ATLAS claim planning                                              |
| `@aephia/atlas-kit/markets`           | Local and faction markets, orders, maker state, discovery                                           |
| `@aephia/atlas-kit/markets/actions`   | Address-only Local Market order, cancellation, and filled-escrow withdrawal planning                |
| `@aephia/atlas-kit/bindings`          | Raw generated C4 clients, unchanged (escape hatch)                                                  |

Combat, scanning, rewards, factions, and loyalty are stable capability entries
that the root client does not compose - import them directly.

## Writing to the game

A planner returns an inert `Plan`: data describing instructions, requirements,
and a human-readable summary. Nothing signs or submits until `executePlan` is
called with an explicitly configured `SageWriteRpc` and external Kit signers.

Show the caller what a Plan does before executing it. Plans compose
deterministically, and can be simulated with a fee-payer address alone.

A fleet that finishes a warp or subwarp keeps reporting that move until
something acts on it. The game settles an elapsed arrival as the first step of
docking, moving again, or starting mining, so a journey is undock, move, dock.
Undocking does not settle it: undocking refuses any fleet that is not already
docked. `planFleetSettleArrival` settles standalone when you want the fleet to
read as arrived on its own; `planFleetStopSubwarp` ends a subwarp early and is
a different action. Docking and movement planners accept stored warp and
subwarp states, use their destination, and rely on chain simulation to reject
movement that has not actually arrived; standalone settlement is optional.

Use `PlanSequence` when a journey requires separately confirmed transactions.
Its itinerary is non-atomic and does not authorize future Plans: a capability
returns `waiting` or freshly prepares one Plan only when reached, and every step
needs fresh authorization through `onBeforeSign`. Persist caller-owned
checkpoints, never signers, transactions, wallet callbacks, or secrets. Do not
blindly retry or automatically resume an unknown, identity-mismatched, or
confirmation-unverifiable checkpoint. An observable public signature can be
reconciled after chain confirmation; an interrupted opaque `invoking` attempt
has no signature and stays unresolved.

## Errors worth handling

- `ACCOUNT_NOT_FOUND` - verify the address and cluster.
- `MISSING_GAME_CONTEXT` - pass `game` when using a custom cluster.
- `INVALID_ENTITY_ID` - ids are 0-65535; Faction and Region ids start at 1.
- `REGISTRY_OUT_OF_SYNC` - refresh and retry; never invent a missing definition.
- `INVALID_ACCOUNT_OWNER`, `INVALID_DISCRIMINATOR`, `ACCOUNT_DECODE_FAILED` -
  stop trusting that account and check the installed binding versions.
- `status: 'unknown'` or `TRANSACTION_OUTCOME_UNKNOWN` - submission may have
  happened. Keep the signature, inspect chain history, reconcile the intended
  action, and **never retry automatically**.

## When the SDK looks wrong

Most apparent SDK bugs are something else: PTR game state that moved since the
data was recorded, an account that genuinely does not exist, RPC flakiness or
rate limiting, a previous-generation `@staratlas` package, or API misuse. Rule
those out first.

Then run the one test that discriminates: read the same account through
`@aephia/atlas-kit/bindings` and compare. If the raw decode is correct and the
translated surface is wrong, it is an SDK bug. If the raw decode is wrong too,
it is upstream or game state - do not file it.

If it survives that, search the existing issues, then **ask the user before
filing anything** and show them the exact title and body first. Standing
approval counts if they have already given it for the session. File against
`Aephia/atlas-kit` using the `SDK bug` form, which lists what to include; the
form applies the `agent:intake` label so the report reaches triage. Without
access to that repository - it is private - write the same report out for the
user to file themselves.

Redact the RPC endpoint: provider URLs routinely embed an API key. Never put a
connection string, a keypair, or any other secret in an issue. Do include the
account addresses and the slot they were read at, from `readMeta`, because that
is what lets the report become a regression fixture once chain state moves on.

## Reading further

Fetch these when a task needs more than the above.

- Everything in one file: https://develop.atlas-kit-docs.pages.dev/llms-full.txt
- Index of the documentation: https://develop.atlas-kit-docs.pages.dev/llms.txt
- Guides, one per capability: https://develop.atlas-kit-docs.pages.dev/guides/
- Generated API reference: https://develop.atlas-kit-docs.pages.dev/reference/
- Star Atlas terms: https://develop.atlas-kit-docs.pages.dev/glossary/