Skip to content

Codex

The Hexanomicon is prophecy. The Codex is law.

The Codex is the written configuration boundary from which one Sepulcher 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 Rune registration. Layout owns the exact paths, permissions, receipts, and Host/Container boundary.

The Prime Inscription

lychd.toml contains process-wide settings only: server and persistence settings, orchestration policy, extension selection, and the bounded Bridge selector. Named runtime or provider instances belong in individual Rune documents beneath runes/. Scroll is reserved for an immutable Spellweaver Pattern revision; configuration is not 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 Vessel. Their values are captured with Settings at startup and omitted from generated TOML and serialized snapshots. Editing an environment variable or secret file does not update a running process; restart it to load the change. The exact credential names and precedence belong to Configuration.

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 Vessel 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 Rune is one validated TOML document beneath the active Rune 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 Rune document in an invented directory creates nothing.

Three rules keep the Archive legible:

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

Current Animator Runes expose model-shaped [[models]] declarations. The Designed general-service form uses [[capabilities]] references to registered interface/profile/driver/ dialect/evidence/resource definitions. Non-model services do not invent a model id, and an "OpenAI-compatible" label never implies every API beneath /v1; see Capabilities and Connectors.

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

The Rite of Binding

Edit the Codex, 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 Codex. 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.