chore: organize current docs and TypeScript maintenance tooling

AGENTS.md

@@ -8,9 +8,13 @@ deployment. Daimon owns only the per-agent runtime boundary.
 
 ## Structure
 
+- `docs/` explains the current package surface and runtime behavior.
+- `archive/` preserves historical plans and audits that are no longer current
+  operating documentation.
 - `src/core/` defines per-agent harness contracts.
 - `src/pi/` implements the contract using Pi's SDK.
 - `src/observability/` records local agent/org activity traces.
+- `src/runtime/` owns the organization-runtime host and durable control plane.
 - `src/examples/` contains runnable local examples and E2E checks.
 
 ## Rules

README.md

@@ -342,14 +342,13 @@ The Pi E2E uses the local Codex CLI subscription auth file to seed an ignored Pi
 `auth.json` under `.runtime/`.
 
 These are live runs: they spend real tokens and require local engine auth
-(`~/.codex/auth.json` for Pi/Codex; mixed-engine and triad additionally need
+(`~/.codex/auth.json` for Pi/Codex; triad additionally needs
 authenticated `grok` and `agy` CLIs on PATH). They are not part of `npm test`.
 
 ```bash
 npm install
 npm run e2e:pi-agent
 npm run e2e:pi-memory-org
-npm run e2e:mixed-engine-org
 npm run e2e:jungian-play-org
 npm run e2e:jungian-triad-org
 ```
@@ -381,14 +380,15 @@ speaks through a Pi agent seeded from local Codex subscription auth. All three
 selves carry the same full archetype set, rotated through the run so every
 archetype gets consulted.
 
-## Design Notes
-
-- `MEMORY-SYSTEM.md` describes the implemented scoped memory runtime.
-- `ENGINE-SYSTEM.md` describes the engine abstraction plan: Pi, local/API
-  model providers, and CLI-backed engines such as `codex`, `claude`, `grok`,
-  and `agy`.
-- Mneme is a sibling package, `@noopolis/mneme`, published separately and used
-  by Daimon in-process for Pi agents. Other runtimes can use Mneme through its
-  MCP server. The agent-facing tools stay named `memory_search`,
-  `memory_register`, and `memory.*` at the protocol boundary because those names
-  are clearer to agents.
+## Docs
+
+Start with `docs/README.md` for the current documentation map:
+
+- `docs/runtime.md` explains the organization-runtime config, control API,
+  schedules, durable wake acceptance, and attention.
+- `docs/engines.md` explains Pi and CLI engine boundaries.
+- `docs/memory.md` explains Daimon's Mneme adapter.
+- `docs/observability.md` explains causal events, raw capture, and world
+  trajectories.
+
+Historical migration plans and audits live under `archive/`.

archive/README.md

@@ -0,0 +1,22 @@
+# Archive
+
+This directory preserves historical design plans, audits, and migration notes
+that are no longer current operating documentation.
+
+Current Daimon docs live in:
+
+- `docs/README.md` for navigation.
+- `docs/runtime.md` for the organization runtime and control API.
+- `docs/engines.md` for Pi, Codex, Grok, and AGY engine boundaries.
+- `docs/memory.md` for Mneme integration.
+- `docs/observability.md` for causal events, raw capture, and world trajectories.
+
+Archived files are kept verbatim except for their path in the repository. Treat
+them as historical evidence, not current authority.
+
+## repository-layout-cleanup
+
+- `MIGRATION_PLAN.md` - historical migration plan.
+- `MEMORY-SYSTEM.md` - historical memory-system design note.
+- `ENGINE-SYSTEM.md` - historical engine-system plan.
+- `docs-audit.md` - historical documentation audit.

docs/README.md

@@ -0,0 +1,38 @@
+# Daimon Docs
+
+Daimon is the per-agent runtime harness for Noopolis. Each harness runs
+one prepared agent; the optional runtime host routes wakes to several harnesses
+with separate agent homes and queues.
+
+Current docs:
+
+- [runtime.md](runtime.md) - runtime config, control endpoints, schedules, durable wake
+  acceptance, and attention.
+- [engines.md](engines.md) - Pi harnessing, CLI engine boundaries, auth storage, and live
+  checks.
+- [memory.md](memory.md) - how Daimon adapts Mneme without owning memory semantics.
+- [observability.md](observability.md) - causal events, raw training capture, and redacted world
+  trajectories.
+
+Historical plans and audits were moved to the [archive](../archive/).
+They are preserved for context, but the files above and the source contracts are
+the current guide.
+
+Source map:
+
+- [`src/core/`](../src/core/) - runtime-neutral harness contracts.
+- [`src/pi/`](../src/pi/) - Pi adapter, prompts, world tools, memory tools, wake handling,
+  and engine-session adapters.
+- [`src/runtime/`](../src/runtime/) - organization-runtime config, HTTP control process, durable
+  wake acceptance, schedules, attention, production tool mounting, and engine
+  readiness.
+- [`src/contracts/`](../src/contracts/) - data-only JSON Schema and contract constants.
+- [`src/observability/`](../src/observability/) - causal event helpers and org observation.
+- [`src/mcp/`](../src/mcp/) - tool server used by production MCP mounts.
+
+Public package entrypoints:
+
+- `@noopolis/daimon`
+- `@noopolis/daimon/pi`
+- `@noopolis/daimon/runtime`
+- `@noopolis/daimon/observability`

docs/engines.md

@@ -0,0 +1,88 @@
+# Engines
+
+[Documentation index](README.md)
+
+Daimon has two layers:
+
+- The runtime-neutral harness contract in `src/core`.
+- Engine adapters under `src/pi` and `src/runtime`.
+
+The simple one-agent contract is:
+
+```ts
+import type { AgentHarnessAdapter, WakeEvent } from "@noopolis/daimon";
+```
+
+`AgentHarnessAdapter.startAgent()` receives one agent's id, name,
+instructions, workspace path, runtime home, and optional tool names. The
+returned handle accepts one `WakeEvent` at a time and returns text, duration,
+and status.
+
+## Pi
+
+`@noopolis/daimon/pi` exports `PiHarnessAdapter` and helpers for Pi auth,
+models, world tools, and traces:
+
+```ts
+import { PiHarnessAdapter } from "@noopolis/daimon/pi";
+```
+
+The Pi adapter creates the runtime-home subdirectories it needs, creates the
+workspace if absent, resolves a Pi model, mounts optional Mneme and world tools,
+and creates awake or dream sessions. Caller instructions are included in the
+system prompt; SOUL or identity-like standing instructions belong in the
+agent's `instructions` field supplied by the caller.
+
+Model intents support built-in Pi providers and explicit OpenAI-compatible or
+Anthropic-compatible endpoints. Endpoint auth is limited to `none` or
+`api_key`; Codex and Claude subscription helpers write Pi auth storage instead.
+
+Auth helpers:
+
+- `seedPiOpenAICodexAuthFromCodex`
+- `seedPiAnthropicAuthFromClaudeCode`
+- `seedPiApiKeyAuth`
+- `createPiOpenAICodexAuthFromCodexToken`
+
+## CLI Engines
+
+The organization runtime accepts `codex`, `grok`, and `agy` engine intents. It
+does not accept arbitrary commands or environment maps in config.
+
+At startup and before each wake, Daimon resolves the executable from a safe
+`PATH`, pins its file identity, probes `--version`, and verifies the selected
+auth boundary.
+
+Codex uses a private `.codex/auth.json` under each agent runtime home. Optional
+Codex config fields are `model`, `reasoningEffort`, and the fixed no-network
+workspace sandbox policy.
+
+The production Grok path uses an external Daimon engine broker with one durable
+subscription credential authority. Agent workers receive scoped capabilities;
+the broker owns refresh and stale-credential recovery. The runtime checks broker
+readiness before admitting Grok agents and verifies their sandbox policy before
+turns. The older credential-lease helper is not the production host path.
+
+AGY uses OS-native secure storage through one private D-Bus and Secret Service
+realm. Enroll it once with:
+
+```bash
+daimon-runtime auth agy login --config /runtime/daimon-runtime.json
+```
+
+Daimon does not accept portable AGY token files, API keys, ADC credentials, or
+ambient D-Bus sessions.
+
+## Live Checks
+
+`npm test`, `npm run typecheck`, and `npm run build` do not call model
+providers.
+
+Live scripts and examples spend real tokens and require local subscription
+auth:
+
+- `npm run live:grok-broker`
+- `npm run e2e:pi-agent`
+- `npm run e2e:pi-memory-org`
+- `npm run e2e:jungian-play-org`
+- `npm run e2e:jungian-triad-org`

docs/memory.md

@@ -0,0 +1,61 @@
+# Memory
+
+[Documentation index](README.md)
+
+Daimon adapts Mneme into agent turns; it does not own memory storage, policy,
+recall, redaction, or MCP. Those semantics live in `@noopolis/mneme`.
+
+For Pi agents, enable memory on `PiHarnessAdapter`:
+
+```ts
+import { PiHarnessAdapter } from "@noopolis/daimon/pi";
+
+const adapter = new PiHarnessAdapter({
+  authPath: "/runtime/pi-auth/auth.json",
+  memory: {
+    runtimeHomePath: "/runtime/memory/writer",
+    source: "daimon",
+    tokenBudget: 20000
+  }
+});
+```
+
+If `memory.runtimeHomePath` is omitted, the adapter uses the agent's
+`runtimeHomePath`. Supplying an explicit memory runtime home lets several Pi
+or CLI sessions share one Mneme bank while keeping their engine homes separate.
+
+Per turn, Daimon asks Mneme to prepare the memory context and then exposes only
+Mneme's model-facing tools for the active trusted context. The context is
+checked against:
+
+- the current agent id;
+- the Mneme authority bank id;
+- the active principal scope;
+- a bounded set of canonical allowed scopes.
+
+Tool arguments are validated against Mneme's tool schemas before execution.
+Unexpected top-level fields are rejected.
+
+Awake wakes use normal working memory behavior. Dream wakes use a fresh
+one-off session under `sessions/dream/<wake-id>-<random>` and prepend dream
+guidance for consolidation work.
+
+Daimon does not automatically write every turn into memory. Agents persist
+memory only by calling Mneme tools such as `memory_register`,
+`memory_summarize`, and `memory_forget`.
+
+Organization-runtime config can declare memory per agent:
+
+```json
+{
+  "memory": {
+    "runtimeHomePath": "/runtime/memory/writer",
+    "source": "daimon",
+    "tokenBudget": 20000
+  }
+}
+```
+
+In production CLI engines, the runtime passes this memory config into the same
+Pi harness layer that mounts production tools. The memory runtime remains
+in-process for Daimon; other runtimes can use Mneme through its own MCP server.

docs/WORLD_TRAJECTORIES.md → docs/observability.md

@@ -1,4 +1,21 @@
-# World trajectories
+# Observability
+
+[Documentation index](README.md)
+
+Daimon records runtime evidence at several layers. The important boundary is
+privacy: full cognition capture is private and opt-in, while causal events and
+world trajectories are minimized surfaces for auditing and joins.
+
+## Causal events
+
+`@noopolis/daimon/observability` exports helpers for Noopolis causal events and
+the org observer. Pi turns also stamp input and output causal events from
+`src/pi/turnCausal.ts`.
+
+The causal layer records event identity, emitter, principal, causes, type, and
+payload. It is the join surface for Moltnet, Mneme, Simfile, and Daimon traces.
+
+## Capture surfaces
 
 Two deliberately separate capture surfaces exist:
 
@@ -15,7 +32,7 @@ is stored under `private-training/pi/raw/turns/` with `0700` directories and
 `0600` files; it is outside ordinary telemetry and is never exported by
 default.
 
-The capture reuses Pi rather than building a parallel cognition recorder:
+Raw capture reuses Pi rather than building a parallel cognition recorder:
 
 - `pi-session.jsonl` is copied byte-for-byte from Pi's native
   `SessionManager`.
@@ -37,9 +54,9 @@ four files and permissions are complete; a failed publication is not retried
 against the same immutable turn path. Retention deletes the oldest per-turn
 capture after the configured maximum.
 
-Stable run/tick/wake identifiers are recorded only as join metadata.
+Stable run, tick, and wake identifiers are recorded only as join metadata.
 Authoritative post-action physics outcomes remain Simfile-owned and are joined
-separately; the raw artifact never becomes simulation authority.
+separately. The raw artifact never becomes simulation authority.
 
 ## Redacted world trajectory
 
@@ -66,3 +83,8 @@ Pi also cannot observe later mechanical effects that happen after an action
 receipt. Simfile may join public contact, kick, goal, score, or next-state
 facts through the exported receipt identifiers. Until that join exists,
 `outcome.status` is `pending_world_join`; Daimon does not invent a reward.
+
+The schema constant is `daimon.world_trajectory.v1`. The implementation lives
+in `src/pi/worldTrajectory.ts`; world tool protocol and authority handling live
+beside it in `src/pi/worldTools.ts`, `src/pi/worldToolProtocol.ts`, and
+`src/pi/worldNudge.ts`.