Ghostlight/AGENTS.md

Ghostlight Instructions

Project Purpose

Ghostlight is a Rust world kernel and the play daemon built on it. Models propose; the kernel admits or refuses. The same kernel is meant to run the simulation behind Aetheria's public story, a persistent cast and storylets, as well as Ghostlight Dungeon, the single-player DM-led client. README.md says what exists today and what does not.

Where State Lives

• Campaign state (targets, rulings, cut specs, reports, verdicts, findings, follow-ups) lives in the Eureka mind, not in this repo. The current campaign is ghostlight-verse; query it through the eureka-state tools.
• notes/ghostlight-verse-target.md and notes/ghostlight-verse-map.md are the campaign's prose target and map. Read the map for probed body facts.
• This repo has no state directory, no state CLI, and no evidence ledger. Do not create one. History belongs in git; durable decisions belong in the mind.
• notes/fresh-workspace-handoff.md is a pointer: what runs, how it deploys, where open work is queried.
• Dated cut documents and postmortems (docs/architecture/*-cut.md, *-postmortem.md) are history. Do not edit them, including their old paths.

Invariants

• The kernel decides. The kernel owns world state through its closed operation set. Models, tools, controllers, and consumers produce proposals only. No code outside the kernel commits world state, and no compatibility writer exists.
• The library is sealed. crates/ghostlight exposes create/open, immutable snapshots, command submission, typed receipts, and the runner and port entry points. Do not publish mutable world types, an ID issuer, a reducer entry, or a journal handle for the convenience of tests or adapters. The seal is proven by the compile_fail doc-tests in crates/ghostlight/src/lib.rs and by crates/ghostlight/tests/external_admission.rs; keep both passing and extend them when the public surface changes.
• Every commit is a command. Everything enters through the mailbox (crates/ghostlight/src/mailbox.rs) as a command. Do not append a commit when reduction produces no canonical mutation.
• A Persona never sees structured state. Persona turns are prose; an Interpreter lowers them to typed proposals, and anything it cannot lower becomes a recorded gap, not invented state.
• Typed state. Runtime documents are CultCache .cc. JSON is for schema publication and boundaries with other systems.
• Credentials. Ghostlight never reads, copies, forwards, or logs a model credential. A consumer never restates a foreign owner's document shape as its own strict struct; read the owner's published contract and test against the real counterpart.
• Canon flows one way. Simulation output never writes back into AetheriaLore or Aetheria's catalog without operator review.

Where Things Are

• Kernel: crates/ghostlight/src/. Its vocabulary and current mechanism: docs/architecture/ghostlight-world-ontology.md. The consumer contract: docs/architecture/ghostlight-world-consumer-api.md.
• Dungeon daemon: crates/ghostlight-dungeon/src/ (runtime.rs for routes and commands, play.rs for the play table, eve.rs for the surface). Interface authority: docs/architecture/ghostlight-eve-native-interface.md.
• Persona membrane: crates/ghostlight-persona-projection/src/lib.rs.
• Browser host: web/. Claude SDK sidecar: sidecar/claude-sdk/.
• Architecture rationale: docs/architecture/ghostlight-dungeon-mvp.md. notes/ghostlight-implementation-plan.md is the historical plan of the 2026-09 rebuild, not the current plan.

Build, Verify, Deploy

Ghostlight Dungeon ships to Linux on Yggdrasil. Idunn freezes an exact commit, runs the locked native Linux tests, builds the daemon and web projection in pinned containers, and seals the release. The steps are deployment/idunn/recipe.toml; the owning runbook is gamecult-ops/runbooks/ghostlight-dungeon-yggdrasil.md.

You are probably reading this on a Windows workstation. That is where the shell is, not where the artifact runs. A Windows compile is not evidence about the Linux release; build for the target, or let the deploy path's builder do it, and say which one you used. Heavy builds and test runs go to Yggdrasil, not the workstation. Deploy only through Idunn (idunn up ghostlight).

For infrastructure, SSH, Idunn, Odin, or Heimdall work, consult F:\Projects\gamecult-ops before acting.

Operating Discipline

• Restate the current mechanism and intended change before substantial edits. Prefer one clear hypothesis per iteration.
• Verify with checks that reflect the real goal, not proxy success. Revert changes that do not clearly improve the target.
• If the diff grows while understanding shrinks, stop and diagnose.
• Delete obsolete authority before adding a new path. Do not keep an old writer alive behind a shim.
• Commit completed work and push it. Merge, confirm the tip by SHA, then delete the branch; push only after reading the test result line.
• In documentation, describe the live system and the current rule directly. No claim of capability without a file that implements it. Keep rejected history short and decision-relevant, or leave it in git.

Aetheria Grounding

• Before writing or generating Aetheria material, check AetheriaLore for the factions, institutions, species or body types, location, and time period involved. Ground detail in the source's material facts: habitat, law, money, route access, surveillance, communication channels, and local failure costs.
• If the source is too vague for a concrete detail, do not bluff. Mark the gap and propose a narrow elaboration for AetheriaLore, subject to operator review.
• Choose a tonal mode on purpose. Aetheria supports wit with stakes, warmth, absurdity, domestic texture, ritual quiet, wonder, horror, noir, and dry systems prose; do not default to constant crisis. Comic precision in the Adams/Pratchett manner is a good default, where jokes reveal stakes instead of dissolving them.
• Establish ordinary life before interruption: routines, work, relationships, small desires, and local accommodations are worldbuilding, not filler.