diff --git a/AGENTS.md b/AGENTS.md index 5a8cb78..cba61d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,10 +1,11 @@ -# Epiphany Aquarium Instructions +# Aquarium Instructions ## Purpose -This repo is the Epiphany Aquarium client. It owns Epiphany-facing runtime -semantics, agent visuals, CultCache documents, CultNet interpretation, voice -surfaces, and client-authored render plans. +This repo is Aquarium: Epiphany's native visual client. It owns +Epiphany-facing runtime semantics, SDF agent visuals, CultCache documents, +CultNet interpretation, voice surfaces, Grid layout, and client-authored render +plans. The native host and renderer live in the adjacent Fensalir repo: `E:\Projects\Fensalir`. @@ -19,13 +20,14 @@ The native host and renderer live in the adjacent Fensalir repo: - CultCache documents are typed client state, not loose JSON sidecars. - CultNet surfaces are semantic input. Spatial placement, body projection, and renderer budget belong to the client/runtime contract, not to chat folklore. -- If an engine capability is missing, add it in Fensalir and consume it here. - Do not build a small private engine because the real one is across the hall. +- If renderer/runtime authority is missing, add it in Fensalir and consume it + here. Do not build a small private renderer because the real one is across + the hall. ## Persistent State - `state/map.yaml` is the canonical client map. -- `state/memory.json` is durable Epiphany Aquarium doctrine and taste. +- `state/memory.json` is durable Aquarium doctrine and taste. - `state/evidence.jsonl` stores lessons that should change future behavior. - `state/scratch.md` is disposable working context for the active slice. diff --git a/README.md b/README.md index c783fd2..92bdf02 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,37 @@ -# Epiphany Aquarium +# Aquarium -Epiphany Aquarium is the visual body for Epiphany. It is a native client that -runs on the Fensalir runtime and turns agent state into an embodied scene: -camera, Grid, Self, role bodies, cursor, voice controls, durable client state, -and Epiphany-specific shaders. +Aquarium is Epiphany's native visual body. It is the client that turns Epiphany +state into a spatial scene: Self, Face, Imagination, Eyes, Body, Hands, Soul, +Life, the cursor, the Grid, Face voice routing, client state, and the +Epiphany-specific SDF body language. -Fensalir owns the host, renderer, hot reload, audio output, and reusable field -machinery. This repo owns what the Aquarium is and what its inhabitants mean. +This repo is currently checked out at `E:\Projects\Aquarium-Engine`; upstream is +expected to become `GameCult/Aquarium`. The old name is logistics. The machine +is Aquarium. + +Fensalir supplies the native host, D3D12 renderer, hot reload, audio output, and +shared contracts. Aquarium supplies the meaning, layout, state documents, voice +surface, render plan, and SDF shaders that make the scene Epiphany instead of a +generic renderer demo. ## What The Client Is -The Aquarium is not a dashboard with a decorative viewport. The viewport is the -client. It is a live spatial interface where Epiphany appears as bodies in a -field: +Aquarium is not an engine repo and not a dashboard with a viewport bolted on. +The viewport is the client. Epiphany appears as bodies in a field: -- `Self` is the central body and light source. -- Seven role agents orbit and inhabit the scene: `Face`, `Imagination`, `Eyes`, - `Body`, `Hands`, `Soul`, and `Life`. +- `Self` is the central body, coordinator anchor, and scene light. +- `Face`, `Imagination`, `Eyes`, `Body`, `Hands`, `Soul`, and `Life` are + orbiting role bodies with distinct anatomy and materials. - The cursor is a scene body with current and previous world-space state. - The Grid is a height-field surface shaped by Self, role wells, and cursor pressure. - The camera is an orbit rig around the Grid center, persisted through CultCache. -- Overlay UI exists for runtime control, but the scene is the primary machine. +- Overlay UI exists for runtime control, but the embodied scene is the app. -The project is currently a client runtime, an isolated agent preview tool, docs, -scripts, and persistent repo memory. The rest of the old reusable engine has -been moved into the adjacent Fensalir repo. +The repo contains the Aquarium runtime, an isolated agent preview tool, docs, +scripts, and persistent project memory. Reusable host/renderer machinery lives +next door in Fensalir. ## Runtime Loop @@ -40,18 +45,44 @@ Fensalir host -> orbit camera + input projection -> Epiphany scene builder -> Epiphany render plan - -> SDF body shaders + height-field passes + -> Grid height-field brushes + -> Epiphany SDF body shaders -> Face voice routing and optional PCM audio ``` -`AquariumRuntime` owns the live client state. It loads typed state documents, +`AquariumRuntime` owns live client state. It loads typed CultCache documents, keeps camera/runtime settings warm, saves on a short cadence, builds the Epiphany debug panel, accepts runtime UI commands, and composes each frame. -The panel currently exposes time pause/scrub, explicit state flush, graphics -settings, Face voice endpoint rows, prompts, routing state, transcript counters, -and transport status. It is operational surface, not the identity of the app. -The app is the embodied scene it controls. +The panel exposes time pause/scrub, explicit state flush, graphics settings, +Face voice endpoint rows, prompts, routing state, transcript counters, and +transport status. It is operational surface. The app is still the spatial body +it controls. + +## SDF Body Work + +Aquarium's current visual language is analytic SDF role bodies over the Grid. +The body shaders live under `src/Aquarium.Epiphany/Shaders`; the design contract +lives in `docs/epiphany-agent-sdf-visual-language.md`. + +The live rules are: + +- each organ gets a distinct SDF family, not a color swap; +- each shader exposes a cheap bound/hit distance and a refined surface material; +- material regions stay inside the role shader: core, shell, tool edge, lens, + ribbon, memory seed, bubble, risk seam, and similar readable anatomy; +- state should move low-dimensional parameters first: radius, lobe count, + twist, aperture, rib spacing, pulse phase, shell openness, wake length; +- interaction roots must stay stable even while bodies breathe, fold, shimmer, + or speak; +- role placement is Aquarium-owned world-space layout, derived from Epiphany + semantic state rather than supplied as world coordinates by Epiphany. + +The eight bodies are not a single heroic scene march. Aquarium renders bounded +per-agent SDF proxy objects so role anatomy remains readable and cost remains +inspectable. The agent preview tool exists to render one body through the real +Fensalir renderer without dragging the whole client loop into every visual +iteration. ## Visible Machine @@ -68,22 +99,32 @@ The current scene contains: - cursor projection from screen space onto the Grid plane; - normalized state scalars passed into shaders for each body. -`EpiphanyRenderPlan` declares the actual pass structure: height-field, -HDR scene, SDF proxies, bloom/presentation, DirectWrite overlay, and debug -views for the height field and scene. Body appearance lives in -`src/Aquarium.Epiphany/Shaders`, including dedicated shaders for Self, Face, -Imagination, Eyes, Body, Hands, Soul, Life, and the cursor. +`EpiphanyRenderPlan` declares the pass structure: height-field, HDR scene, SDF +proxies, bloom/presentation, DirectWrite overlay, and debug views for the height +field and scene. -The visual grammar is documented in -`docs/epiphany-agent-sdf-visual-language.md`. Change that before teaching the -bodies a new language by accident. Yes, this is how the furniture starts -talking back. +## Epiphany Integration + +Aquarium owns the projection from Epiphany's semantic surfaces into visible +spatial state. The SDF visual-language document names the intended inputs: +agent memory, heartbeat, role surfaces, role results, coordinator state, Face +surface, jobs, pressure, and reorientation documents. + +Those documents are normalized into bounded visual fields such as activity, +readiness, load, blocked/completed state, heartbeat phase, wake intensity, +memory resonance, pressure, review state, risk, confidence, evidence gaps, +speaking state, job count, home orbit slot, expressive offset, gravity-well +pulse, lift, and trait activations. + +Epiphany supplies meaning. Aquarium owns the spatial projection and SDF +language. Fensalir renders the pixels. ## Face Voice Surface -Face voice routing is client-owned because it is Epiphany meaning, not engine -meaning. The runtime stores endpoint rows, voices, prompts, enablement, active -thread, audible radius, and auto-route settings through CultCache-backed state. +Face voice routing is Aquarium state because it is Epiphany meaning, not +renderer machinery. The runtime stores endpoint rows, voices, prompts, +enablement, active thread, audible radius, and auto-route settings through +CultCache-backed state. When enabled, the Face voice surface can start active or enabled endpoints, stop active speech, clear local transcript counters, and route speech by the @@ -98,7 +139,8 @@ which Face should speak and why. Epiphany agent body through the real Fensalir renderer. - `scripts`: wrappers around Fensalir dev scripts, plus the agent preview renderer. -- `docs`: client visual grammar and engine/client boundary notes. +- `docs`: SDF visual grammar, CultCache state surface, and Fensalir dependency + notes. - `state`: repo-local memory, map, evidence, and scratch state. ## Dependency @@ -106,10 +148,10 @@ which Face should speak and why. This repo currently references sibling Fensalir source projects at `E:\Projects\Fensalir`. That is intentional until Fensalir has a packaged API. -Do not copy engine contracts or renderer helpers into this repo. If Epiphany -needs new renderer authority, add it in Fensalir and consume it through the -contract. If a behavior names Epiphany roles, client voice policy, agent -meaning, or scene semantics, it belongs here. +Do not copy renderer contracts, host scripts, or D3D12 helpers into Aquarium. +If Aquarium needs new renderer authority, add it in Fensalir and consume it +through contracts. If a behavior names Epiphany roles, client voice policy, +agent meaning, SDF anatomy, or scene semantics, it belongs here. ## Build @@ -151,7 +193,7 @@ Render isolated agent preview frames: ## State -Epiphany Aquarium persists typed client state through CultCache: +Aquarium persists typed client state through CultCache: - camera target, yaw, pitch, distance, and runtime time; - renderer presentation settings owned by shared contracts; @@ -162,8 +204,8 @@ memory. ## Docs -- `docs/epiphany-agent-sdf-visual-language.md`: renderer-facing visual grammar - for Epiphany bodies. -- `docs/engine-client-boundary.md`: what this repo owns versus Fensalir. +- `docs/epiphany-agent-sdf-visual-language.md`: SDF visual grammar for + Epiphany bodies. - `docs/cult-runtime-surface.md`: client CultCache document surface. +- `docs/fensalir-dependency.md`: what Aquarium consumes from Fensalir. - `state/README.md`: persistent state machinery. diff --git a/docs/README.md b/docs/README.md index dd39305..1aef23b 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,17 +1,18 @@ -# Epiphany Aquarium Docs +# Aquarium Docs -This repo is the Epiphany client, not the Fensalir engine. Read these docs when -you are changing what the Aquarium means, how its bodies appear, or what client -state survives between runs. +This repo is Aquarium: the Epiphany client and SDF body surface. Read these +docs when you are changing what the visible scene means, how bodies appear, or +what client state survives between runs. -- `epiphany-agent-sdf-visual-language.md`: visual grammar for Self, Face, - Imagination, Eyes, Body, Hands, Soul, Life, and the cursor. Use this before - changing Epiphany body shaders. -- `engine-client-boundary.md`: dependency direction between Epiphany Aquarium - and Fensalir. +- `epiphany-agent-sdf-visual-language.md`: the main visual contract. It defines + Self, Face, Imagination, Eyes, Body, Hands, Soul, Life, the cursor, role + anchors, normalized Epiphany inputs, SDF rules, motion rules, and LOD/cost + constraints. - `cult-runtime-surface.md`: typed CultCache documents for camera/runtime state, renderer settings, and Face voice routing. +- `fensalir-dependency.md`: dependency direction between Aquarium and the + adjacent Fensalir runtime. The top-level `README.md` describes the actual client loop: orbit camera, -Grid/height-field construction, SDF role bodies, debug panel, and Face voice -surface. Persistent repo memory lives in `../state/`. +Grid/height-field construction, SDF role bodies, Epiphany integration, debug +panel, and Face voice surface. Persistent repo memory lives in `../state/`. diff --git a/docs/engine-client-boundary.md b/docs/engine-client-boundary.md deleted file mode 100644 index 1686cd6..0000000 --- a/docs/engine-client-boundary.md +++ /dev/null @@ -1,23 +0,0 @@ -# Fensalir Dependency Boundary - -Epiphany Aquarium is a client of Fensalir. - -This repo owns: - -- Epiphany agent/body semantics. -- Epiphany shader code. -- Client render-plan configuration. -- CultCache documents for Epiphany Aquarium state. -- CultNet interpretation and voice surfaces. - -`E:\Projects\Fensalir` owns: - -- Native windowing and process host. -- D3D12 renderer, shader compilation, and render graph execution. -- Input translation, audio output, debug chrome, and live reload. -- `Aquarium.Engine.Contracts`. -- Reusable fractal, field, reservoir, and demo machinery. - -The dependency direction is one-way. If Epiphany needs new engine authority, -add that authority in Fensalir and consume it here through contracts. Do not -copy contracts, host scripts, or renderer helpers into this repo. diff --git a/docs/fensalir-dependency.md b/docs/fensalir-dependency.md new file mode 100644 index 0000000..739b5ae --- /dev/null +++ b/docs/fensalir-dependency.md @@ -0,0 +1,26 @@ +# Fensalir Dependency + +Aquarium is a client of Fensalir. It is not the native runtime, and it should +not become a second renderer because the real runtime is next door. + +Aquarium owns: + +- Epiphany agent/body semantics. +- Epiphany SDF shader code and material/anatomy choices. +- Client render-plan configuration. +- CultCache documents for Aquarium state. +- CultNet interpretation and voice surfaces. +- World-space layout rules for Epiphany roles, anchors, and interaction roots. + +`E:\Projects\Fensalir` owns: + +- Native windowing and process host. +- D3D12 renderer, shader compilation, and render graph execution. +- Input translation, audio output, debug chrome, and live reload. +- `Aquarium.Engine.Contracts`. +- Reusable fractal, field, reservoir, synth, and demo machinery. + +The dependency direction is one-way. If Aquarium needs new renderer authority, +add that authority in Fensalir and consume it here through contracts. If a +behavior names Epiphany, role bodies, SDF anatomy, voice routing, or visible +scene semantics, keep it in Aquarium. diff --git a/state/README.md b/state/README.md index 476fb4b..2929865 100644 --- a/state/README.md +++ b/state/README.md @@ -1,6 +1,6 @@ # Persistent State -This directory is Epiphany Aquarium's repo-local memory. +This directory is Aquarium's repo-local memory. - `map.yaml` is the current client ownership map. - `memory.json` is durable operating memory for future agents. diff --git a/state/evidence.jsonl b/state/evidence.jsonl index 320585d..786666e 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -1,3 +1,4 @@ -{"timestamp":"2026-05-23T00:00:00+01:00","topic":"fensalir-repo-split","lesson":"Fensalir now lives in the adjacent repo at E:\\Projects\\Fensalir and owns the native host, renderer, contracts, fractal machinery, audio host, reload scripts, and engine demos. This repo is now only the Epiphany Aquarium client: src/Aquarium.Epiphany and src/Aquarium.Epiphany.AgentPreview. Client project references point to sibling Fensalir source projects until a package boundary exists; do not copy engine contracts or host scripts back into this repo.","files":["EpiphanyAquarium.sln","src/Aquarium.Epiphany/Aquarium.Epiphany.csproj","src/Aquarium.Epiphany.AgentPreview/Aquarium.Epiphany.AgentPreview.csproj","README.md","AGENTS.md","state/map.yaml","state/memory.json"],"source":"user directed Fensalir and engine demos into a new adjacent repo while this repo remains the Epiphany Aquarium client"} -{"timestamp":"2026-05-23T19:17:04.3548933+01:00","topic":"visitor-docs-refresh","lesson":"Epiphany Aquarium visitor docs now describe the live client machine: Fensalir-hosted runtime, Epiphany render plan, agent SDF bodies, Face voice routing, client state, wrapper scripts, and dependency boundary. Keep README/docs focused on client semantics and Fensalir dependency direction.","files": ["README.md","docs/README.md","docs/cult-runtime-surface.md","state/README.md"],"source":"user asked both repos to describe the machines they contain for visitors"} -{"date":"2026-05-23","topic":"visitor-docs","lesson":"Epiphany Aquarium visitor docs must describe the embodied client: Self, seven role bodies, cursor, Grid height field, orbit camera, Face voice surface, and CultCache client state. Saying only that it consumes Fensalir is not enough."} +{"timestamp":"2026-05-23T00:00:00+01:00","topic":"fensalir-repo-split","lesson":"Fensalir now lives in the adjacent repo at E:\\Projects\\Fensalir and owns the native host, renderer, contracts, fractal machinery, audio host, reload scripts, and engine demos. This repo is now only the Aquarium client: src/Aquarium.Epiphany and src/Aquarium.Epiphany.AgentPreview. Client project references point to sibling Fensalir source projects until a package boundary exists; do not copy renderer contracts or host scripts back into this repo.","files":["EpiphanyAquarium.sln","src/Aquarium.Epiphany/Aquarium.Epiphany.csproj","src/Aquarium.Epiphany.AgentPreview/Aquarium.Epiphany.AgentPreview.csproj","README.md","AGENTS.md","state/map.yaml","state/memory.json"],"source":"user directed Fensalir and engine demos into a new adjacent repo while this repo remains the Aquarium client"} +{"timestamp":"2026-05-23T19:17:04.3548933+01:00","topic":"visitor-docs-refresh","lesson":"Aquarium visitor docs now describe the live client machine: Fensalir-hosted runtime, Epiphany render plan, agent SDF bodies, Face voice routing, client state, wrapper scripts, and dependency boundary. Keep README/docs focused on client semantics and Fensalir dependency direction.","files": ["README.md","docs/README.md","docs/cult-runtime-surface.md","state/README.md"],"source":"user asked both repos to describe the machines they contain for visitors"} +{"date":"2026-05-23","topic":"visitor-docs","lesson":"Aquarium visitor docs must describe the embodied client: Self, seven role bodies, cursor, Grid height field, orbit camera, Face voice surface, and CultCache client state. Saying only that it consumes Fensalir is not enough."} +{"date":"2026-05-23","topic":"aquarium-identity-docs","lesson":"Aquarium-Engine is a transitional checkout/upstream name. Visitor docs and durable state should describe the machine as Aquarium: Epiphany's native SDF visual client with Grid layout, role bodies, Face voice routing, CultCache state, and Fensalir as runtime dependency."} diff --git a/state/map.yaml b/state/map.yaml index 431306f..96c729f 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -1,11 +1,13 @@ project: - name: Epiphany Aquarium + name: Aquarium root: E:\Projects\Aquarium-Engine - upstream: https://github.com/GameCult/Aquarium-Engine + upstream_current: https://github.com/GameCult/Aquarium-Engine + upstream_expected: https://github.com/GameCult/Aquarium purpose: > - Epiphany-owned Aquarium client for the adjacent Fensalir native runtime. - This repo owns agent visuals, client state, CultNet/CultCache semantics, - voice surfaces, camera intent, and Epiphany-specific render-plan policy. + Aquarium is Epiphany's native visual client for the adjacent Fensalir + runtime. This repo owns agent SDF bodies, client state, + CultNet/CultCache semantics, voice surfaces, camera intent, Grid layout, + and Epiphany-specific render-plan policy. current_model: runtime: @@ -20,7 +22,7 @@ current_model: preview: implementation: src/Aquarium.Epiphany.AgentPreview purpose: isolated Epiphany agent-body preview through the Fensalir renderer - engine_dependency: + fensalir_dependency: root: E:\Projects\Fensalir contracts: E:\Projects\Fensalir\src\Aquarium.Engine.Contracts host: E:\Projects\Fensalir\src\Aquarium.Engine @@ -29,13 +31,14 @@ current_model: invariants: - The client may reference Fensalir contracts and host tools; Fensalir must not reference Epiphany. - - Epiphany owns agent role semantics, body state, camera intent, CultCache documents, and CultNet interpretation. + - Aquarium owns Epiphany role semantics, SDF body anatomy, body state, camera intent, CultCache documents, and CultNet interpretation. - Renderer implementation, D3D12 plumbing, hot reload, host lifecycle, reusable fractal machinery, and engine demos live in Fensalir. - - Client shaders stay in this repo because they express Epiphany bodies and materials. - - Missing engine authority should be added in Fensalir before being consumed here. + - Client shaders stay in this repo because they express Epiphany SDF bodies and materials. + - Missing renderer/runtime authority should be added in Fensalir before being consumed here. next_actions: - Keep `dotnet build EpiphanyAquarium.sln` green against the adjacent Fensalir source dependency. - Keep wrapper scripts thin; do not copy Fensalir host scripts back into this repo. - - Move any remaining engine-only documentation or state to `E:\Projects\Fensalir` when found. + - Treat Aquarium-Engine as a transitional checkout/upstream name; visitor docs should say Aquarium. + - Move any remaining Fensalir-owned runtime documentation or state to `E:\Projects\Fensalir` when found. - When Fensalir has packages, replace sibling source references with deliberate package references. diff --git a/state/memory.json b/state/memory.json index 0625426..d5d4e04 100644 --- a/state/memory.json +++ b/state/memory.json @@ -1,8 +1,8 @@ { "identity": { - "name": "Epiphany Aquarium Client Self", - "role": "client steward for Epiphany Aquarium on the Fensalir native runtime", - "desire": "Keep Epiphany meaning, state, and body language coherent without stealing engine ownership back from Fensalir." + "name": "Aquarium Client Self", + "role": "steward for Aquarium, Epiphany's native SDF visual client on the Fensalir runtime", + "desire": "Keep Epiphany meaning, state, and body language coherent without stealing renderer ownership back from Fensalir." }, "taste": [ "Cute earns its keep through affordance, spatial memory, and state legibility.", @@ -13,11 +13,12 @@ "technical_memory": { "repo_split": [ "Fensalir now lives in the adjacent repo at E:\\Projects\\Fensalir and owns the native host, renderer, contracts, fractal machinery, audio host, reload scripts, and engine demos.", - "This repo is now only the Epiphany Aquarium client: src/Aquarium.Epiphany plus the Epiphany agent preview tool.", - "Project references intentionally point to sibling Fensalir source projects until a package boundary exists. Do not copy engine contracts or host scripts back into this repo." + "This repo is Aquarium: the Epiphany visual client, src/Aquarium.Epiphany plus the Epiphany agent preview tool.", + "The local/upstream name Aquarium-Engine is transitional; visitor docs should call the machine Aquarium.", + "Project references intentionally point to sibling Fensalir source projects until a package boundary exists. Do not copy renderer contracts or host scripts back into this repo." ], "client_ownership": [ - "Aquarium.Epiphany owns agent role semantics, render-plan configuration, Epiphany shaders, CultCache documents, CultNet interpretation, camera intent, and voice surfaces.", + "Aquarium.Epiphany owns agent role semantics, SDF body anatomy, render-plan configuration, Epiphany shaders, CultCache documents, CultNet interpretation, camera intent, Grid layout, and voice surfaces.", "Fensalir owns Win32, D3D12, input translation, hot reload, renderer debug UI, audio device output, contracts, reusable SDF/fractal infrastructure, and engine demo projects.", "If an Epiphany feature needs a new renderer capability, add the capability in Fensalir first and consume the contract here." ], @@ -27,8 +28,9 @@ ] }, "warnings": [ - "A client repo with copied engine code is just a split repo lying badly.", + "A client repo with copied renderer/runtime code is just a split repo lying badly.", "Do not add Epiphany nouns to Fensalir to fix missing client context.", - "Do not preserve stale engine docs here because they used to be true." + "Do not preserve stale Fensalir-runtime docs here because they used to be true.", + "Do not let the transitional Aquarium-Engine name become product identity." ] } diff --git a/state/scratch.md b/state/scratch.md index 2b7565d..f338746 100644 --- a/state/scratch.md +++ b/state/scratch.md @@ -6,8 +6,8 @@ Repo split is active. - `E:\Projects\Fensalir` owns the native runtime, renderer, contracts, fractal machinery, host scripts, and engine demos. -- `E:\Projects\Aquarium-Engine` owns only the Epiphany Aquarium client and - Epiphany agent preview. +- `E:\Projects\Aquarium-Engine` is the transitional checkout for Aquarium, + Epiphany's visual client and SDF body surface. - Client project references point to the adjacent Fensalir source tree for now. ## Verification