Sonder_Engine AGENTS.md

Editing Guide for Coding Agents

This file is the operational map for changing Sonder Engine safely. It is written for both human contributors and AI coding agents.

First-pass orientation

Before editing behavior:

1. Read Design.md § Genre-agnostic substrate, world-specific law before adding or specializing a mechanic.
2. Read docs/guides/PIPELINE.md for execution order and ownership boundaries.
3. Search docs/CODE_MAP.md for the handler or function involved.
4. Read docs/guides/DATABASE.md before changing persistent state, archives, or restore paths.
5. Read the relevant schema in llm/schemas.py before changing any model output.
6. Read the corresponding commit function before adding fields that should persist.
7. Read docs/guides/TESTING.md, find the nearest regression test, and run the narrow test first.

docs/CODE_MAP.md is generated; never hand-edit it. Regenerate and verify it after moving or adding functions:

make map
make structure

AGENTS.md, Design.md and everything in docs/guides/ are the maintained guidance set — current implementation authority, changed in the same commit as the behaviour. docs/design/, docs/experiments/ and docs/archive/ are context rather than authority: a design note argues for one subsystem, an experiment record reports one unrepeatable run, and an archived document has been superseded. Check any of their claims against source and the maintained guides before acting on them. docs/README.md is the index and says which is which.

Edit routing

Charter identity changes route through world/charter_identity.py, world/charter_model.py and world/charter_runtime.py. The Charter/body dict key is permanent identity. A generated personal name is materialized once; profile edits affect only unnamed future bodies. A pool sizes the law's phonology, never the population: the allocator spreads each spread_components element breadth-first (family, because recurrence inside one generated population implies kinship nobody authored, plus any component address_components says the law calls people by alone) — authored pool values first, then the extension lane (extension_profile: the profile's own syllable parts, else parts derived from the pool's own words by derived_name_parts), with reuse only once the whole reachable space is spent. Spreading is preference; name_is_reserved stays the only refusal beside components_repeat (a name may not double its own component). No pool means no derivation — the no-implicit-default doctrine is unchanged, and both minting paths (materialize_body_names and story/naming.minted_presence_name) share the extension. Rank/post titles are aliases, and transcript color derives from the permanent identity so title changes and promotion do not repaint the person. Name learning must still prove an exact delivered line and physical co-location; index the roster once per beat rather than scanning a large institution once per quote.