Documentation: 0.5.0 (source: v0.5.0).
# Council Rank

> The account-wide rank, XP categories, the research tree, and the perks a character has in effect.

Markdown source of https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/council-rank/ — see https://docs-v0-5-0.atlas-kit-docs.pages.dev/ai/ for the full machine-readable surface.

Council Rank is what a character has become: the rank itself, the level in
each activity, the research unlocked, and the perks in
effect. It all hangs off the character, and all of it is readable.

:::game[Council Rank is the account, not the pilot]
Council Rank is a player's account-wide progression level in SAGE, raised by
earning XP across everything they do. Rising through the ranks is what unlocks
the bigger toys: research, larger ships, additional fleets, buildings, and
other capabilities. The category levels — pilot, mining, crafting, combat —
grow alongside it, each fed by its own activity.
:::

## Reading the rank and the levels

XP lives on the character, but a level is a judgement — it depends on the
game's thresholds, not on the raw number alone. The progression read does the
join for you:

```ts
import { getCharacterProgressionForProfile } from '@aephia/atlas-kit/identity';

const progression = await getCharacterProgressionForProfile(
  ctx,
  profileAddress,
);

progression.xp.councilRank.level; // the account-wide rank
progression.xp.pilot.level; // one activity category
```

Every category — `councilRank`, `pilot`, `mining`, `crafting`, `building`,
`combat`, `dataRunner`, `dailyXp` — carries `earned`, `spent`, and `level`,
and `progression.xpDefinitions` holds the thresholds the levels were judged
against, so you can also render "how far to the next one".

> **Runnable example — Read Council Rank and research.** The account-wide rank and category levels, plus the research catalog. Run it in the browser at https://docs-v0-5-0.atlas-kit-docs.pages.dev/guides/council-rank/.

## The research tree

The catalog is game data — the same for everyone, independent of any
character:

```ts
import { getResearchCatalog } from '@aephia/atlas-kit/identity';

const catalog = await getResearchCatalog(ctx);
const node = catalog.nodes[0];
```

Each node lists what it costs (XP from specific categories at minimum levels,
ATLAS, sometimes resources) and — the part that matters — `node.modifier`:
the perk it grants when unlocked.

:::game[Research is how ranks become power]
The research tree is where progression pays out. Each node has a price — XP
from specific categories at minimum levels, ATLAS, sometimes resources — and
activating a node grants its perk: a permanent improvement such as a larger
fleet limit, faster warp, or cheaper crafting. Respeccing lets a player take
back spent points and choose differently.
:::

## What a character has unlocked

The character's side of research is on the character itself:

```ts
const unlocked = character.modifiers.unlockedNodes;
const levels = character.modifiers.nodeLevels;
```

And the sum of everything in effect — every unlocked perk applied — is one
bundle of values:

```ts
const inEffect = character.modifiers.values;

inEffect.fleetSize; // how many fleets this character may field
inEffect.warpSpeedModifier;
inEffect.craftingEfficiencyModifier;
```

This is the answer to "can this player add another fleet": compare
`character.modifiers.values.fleetSize` against `character.counts.fleets`. The
same `counts` object tracks claim stakes and crafting habs.

## Gotchas

**Levels are derived, not stored.** The raw XP is on the character; the level
comes from judging it against the game's thresholds. Use the progression read
rather than inventing your own cutoffs.

**Earned and spent are different numbers.** Research costs XP, so a category
shows both what was ever earned and what has been spent from it. A level is
about earning; affordability is about what is left.

**The catalog carries no character state.** `getResearchCatalog` is
deliberately character-free. Whether a node is unlocked lives on the
character's `modifiers`, not on the catalog.

## Reference

- [`identity`](/reference/identity/) — every export in this entry
- [You](/guides/identity/) — the chain that leads to the character
- [Crafting habs](/guides/crafting-habs/) and
  [claim stakes](/guides/claim-stakes/) — two of the things ranks unlock