Codex

The HexanomiconOfficial DocsThe Official Docs is prophecy. The CodexSettings FolderSettings Folder is law.

The CodexSettings Folder is the written configuration boundary from which one SepulcherBodyThe Body is summoned. By default it lives at ~/.config/lychd/; XDG_CONFIG_HOME may move the root without changing its inner geography.

~/.config/lychd/
├── lychd.toml
└── runes/
    └── animator/
        ├── soulstones/
        └── portals/

Configuration owns loading, validation, and RuneService Config FileService Config File registration. Layout owns the exact paths, permissions, receipts, and Host/Container boundary.

The Prime Inscription

Put only process-wide settings in lychd.toml: server and persistence settings, orchestration policy, extension selection, and the bounded Bridge selector. Give each named runtime or provider instance its own RuneService Config FileService Config File document beneath runes/. Reserve ScrollWorkflow VersionWorkflow Version for an immutable SpellweaverWorkflow EngineWorkflow Engine PatternWorkflowWorkflow revision; configuration declares the body's intent without becoming executable workflow law.

Settings resolve in one order: explicit construction → environment overrides → lychd.toml → Pydantic file secrets → model defaults. LychD loads no .env; nested sections load no separate sources.

Set database and signing credentials in the process environment or mounted secret files before starting the VesselEngine RoomEngine Room. Settings captures their values at startup and excludes them from generated TOML and serialized snapshots. Restart to load a later change; editing the environment or secret file cannot update the running process. Configuration gives the exact credential names and precedence.

The former host-native LYCHD_RUNTIME_SECRETS=podman-core@1 source is retired; explicit selection refuses before credential I/O. The container consumes its separately mounted /run/secrets inputs through ordinary Settings sources. The host Podman secret adapter retains its bind/access responsibilities without becoming application startup transport. See the retired source boundary.

An incomplete law may be edited; it may not half-enter the body. The complete configuration must validate before infrastructure projection begins.

The generated foundation selects the caged Host Reactor:

[orchestration.switching]
actuator = "host-reactor"

actuator = "systemd" remains a typed host-adapter mechanism for explicit tests; it does not select a supported host-native VesselEngine Room or bypass the managed container's Host Reactor boundary. Runtime transitions gives the Reactor path and acknowledgement settings; Orchestrator owns the validated host handoff and recovery outcomes.

The Rune Archive

A RuneService Config FileService Config File is one validated TOML document beneath the active RuneService Config File root. Its path determines its owning family and named instance. It is frozen intent—not a running service or generated Quadlet.

runes/animator/soulstones/<family>/<instance>.toml
runes/animator/portals/<family>/<instance>.toml

Extensions may register anchors. The Librarian accepts only declared anchors and validated schemas; a RuneService Config File document in an invented directory creates nothing.

Three rules keep the ArchiveLong-term MemoryLong-term Memory legible:

• SoulstoneLocal ModelLocal Model model paths are container paths, normally below /models; a volume binding names the Host source.
• RunesService Config Files name secrets; they never embed secret values.
• Valid RunesService Config Files feed lychd bind; they never edit systemd or Podman state themselves.

Current AnimatorModel RuntimeModel Runtime RunesService Config Files describe models through [[models]]. The Designed general-service form instead uses [[capabilities]] references to registered interface, profile, driver, dialect, evidence, and resource definitions. It gives non-model services a way to declare themselves without inventing a model id. In either case, establish the exact supported surface: an "OpenAI-compatible" label cannot imply every API beneath /v1. Continue through Capabilities and Connectors.

Read Animator, Soulstone, and Portal for the built-in families.

The Rite of Binding

Edit the CodexSettings FolderSettings Folder, then project it from the stable Summoning checkout, under the same operator user and XDG environment:

uv run --extra postgres-binary lychd bind

Binding follows one direction:

Codex
→ load declared anchors
→ validate the complete configuration
→ calculate one binding plan
→ transactionally publish owned Quadlet and user-unit files
→ reload systemd

Generated Quadlets live by default in ~/.config/containers/systemd/; selected plain user units live in ~/.config/systemd/user/. Both are shared operator directories, not a common workbench. LychD owns only the exact filenames recorded in the same-UID, mode-0600 .lychd-owned.json receipt.

If a desired filename exists outside that receipt, binding fails closed: it neither adopts, overwrites, nor deletes the operator's file. Review the collision deliberately, then bind again.

Never hand-edit a generated file named by the receipt. The next successful bind reconciles it from the CodexSettings Folder. Mutation failure is either cleanly rolled back or retains indeterminate recovery evidence. State of Work records the core CLI rites as Partial; repository tests do not claim real systemd or Podman actuation.

To change the manifestation, amend the law.