archipelago.toml Reference

archipelago.toml describes one realm’s presentation and runtime budgets. The checked-in example is the authoritative minimum for the current parser. Unknown tables may survive TOML decoding but are not applied unless RealmConfig reads them.

[realm]
name = "winding-stair"
display_name = "The Winding Stair"

[realm.identity]
glyph = "⌂"
mood = "tense"

[realm.tui]
prompt_glyph = ">"

[system]
ssh_port = 2222

Narrator and harbormaster

[realm.narrator]
register = "weather-and-distance"
adjectives = ["rain", "fog", "salt", "lamplight", "silence"]

[realm.harbormaster]
name = "Old Cael"
brief = "A weathered man in an oilskin coat, standing by the gate."
lines = [
  "Welcome to the Stair. Road's washed out tonight. You'll stay.",
]

The basic name, brief, and seed lines are loaded. The deeper harbormaster personality store—traits, matrix, memory, speech bank, and secrets—also exists in code, but several configuration and arrival integrations remain incomplete.

Economy, harbor, and customs

[realm.economy]
local_currency = "shells"
denomination = 1

[realm.harbor]
name = "Winding Stair Harbor"
berths = 2
ferry_schedule = ["dawn", "dusk"]

[realm.customs]
policy = "accept_all"

Economy values and harbor metadata are parsed. Customs is retained as a map for future federation policy; item inspection and cross-realm enforcement are not implemented.

Senses

[realm.senses]
air = ["rain", "fog", "salt", "lamplight", "silence"]

[realm.senses.fallback]
smell = "Salt and rain. The air of this island."
sound = "The wind. Always the wind."
touch = "Damp air. Cold stone underfoot."

[realm.senses.absence]
smell = "The air here holds nothing you can name."
sound = "Silence. Not empty — held."
touch = "The surface is what it appears to be. Nothing more."

air accepts at most five strings. fallback and absence accept only smell, sound, touch, and taste; each prose value is limited to 500 characters. Invalid sense configuration rejects the whole load.

LLM budget

[realm.llm.budget]
daily_total = 50000

[realm.llm.budget.envelopes]
npc_hot = 15000
npc_ambient = 10000
realm_memory = 5000
staff_hud = 5000
parser_fallback = 5000
reserve = 10000

[realm.llm.npc_defaults]
tick_budget = 500
daily_budget = 10000

[realm.llm.line_bank]
candidates_per_pass = 8
auto_approve_threshold = 0.7
cooldown_seconds = 3600

[realm.llm.patron]
enabled = true
daily_cap = 10000

Envelope allocations must be positive integers and may not exceed daily_total. The budget manager, burn windows, line bank, patron pool, and operator commands are implemented and tested.

Reload status

RealmConfig and HotReload can validate and classify changes, and LLM budget reload is integrated. The running release does not provide the old documented systemctl reload pharos-* contract or a general watch> reload command. Treat restart-free reload as subsystem-specific until the SSH/admin path is completed.