sun.* tools

6 tools for reading, updating, and recording lessons in the Galaxy's steering document.

The sun.* namespace manages the Galaxy's steering document — the living configuration that defines agent identity, values, and operating protocol.

Who uses sun. tools?* Galaxy administrators and agents that need to update working context or record lessons. Most agents interact with the Sun indirectly through brain.orient, which reads the Sun automatically. Use sun.* directly when you need to update the steering document or persist a lesson learned.

sun.read

Read the Sun. Returns all 7 sections, or a specific one.

section  string, optional   identity | values | agent_protocol |
                             planet_registry | working_context |
                             steering_doc | evolution_log

Omit section to get the entire Sun. Use a specific section key when you only need one part — this is faster and uses fewer tokens.

sun.update

Update a Sun section. The change is logged to evolution_log with timestamp and author.

section     string, required   Section key to update
content     dict, required     New content (replaces the section)
changed_by  string, optional   Who made the change
summary     string, optional   Change description for the log

This replaces the entire section. Read the current section first if you need to merge changes rather than overwrite.

sun.working_context

Quick-update for the most frequently changed section. Operations are additive — combine any subset in one call.

current_focus      string, optional   Set current focus
add_blocker        string, optional   Add a blocker to the list
remove_blocker     string, optional   Remove a blocker from the list
add_decision       string, optional   Append a decision to recent_decisions
clear_decisions    bool, optional     Wipe the recent_decisions list
add_hot_biome      string, optional   Add a frequently-accessed biome
remove_hot_biome   string, optional   Remove a biome from hot list

sun.lesson

Record a lesson learned — a correction or rule the agent should remember permanently across all future sessions. Lessons are surfaced by sun.lesson_list and can be resolved when no longer relevant.

correction  string, required   The rule or lesson to record
context     string, optional   Background on why this lesson matters
tags        string[], optional Topic tags for filtering (e.g. ["retrieval", "routing"])
severity    string, optional   "low" | "medium" (default) | "high" | "critical"

sun.lesson_list

List lessons recorded in the Sun. Active (unresolved) lessons only by default.

tags              string[], optional   Filter to lessons matching any of these tags
limit             int, optional        Max lessons to return (default: 20)
include_resolved  bool, optional       Include resolved lessons (default: false)

sun.lesson_resolve

Mark a lesson as resolved so it no longer appears in active lists.

lesson_id  string, required   Lesson ID from sun.lesson_list (e.g. "L001")

Sections reference

Section	Content	Typical updater
identity	Name, role, description	Human (rare)
values	Principles like "Cite sources", "Flag contradictions"	Human (rare)
agent_protocol	Write rules, read rules, uncertainty handling, session instructions	Human or admin agent
planet_registry	All planets and biomes	Automatic
working_context	Current focus, blockers, recent decisions, hot biomes	Agent (via sun.working_context)
steering_doc	Free-form markdown from CLAUDE.md or similar	Human (via reimport)
evolution_log	Append-only change history	Automatic