chore(deps-dev): bump @tailwindcss/vite from 4.2.4 to 4.3.0 in /src/dashboard

.github/dependabot.yml

@@ -26,7 +26,7 @@ updates:
           - "@wilds/*"
 
   - package-ecosystem: "npm"
-    directory: "/src/cli/dashboard"
+    directory: "/src/dashboard"
     schedule:
       interval: "daily"
     open-pull-requests-limit: 3

.github/workflows/deploy.yml

@@ -73,13 +73,13 @@ jobs:
             popd >/dev/null
           }
           check "." "Root"
-          check "src/cli/dashboard" "Dashboard"
+          check "src/dashboard" "Dashboard"
 
       - name: Guard against pnpm-workspace contamination in lockfiles
         run: |
           set -e
           fail=0
-          for f in package-lock.json src/cli/dashboard/package-lock.json; do
+          for f in package-lock.json src/dashboard/package-lock.json; do
             if [ ! -f "$f" ]; then continue; fi
             if grep -q 'node_modules/\.pnpm/' "$f"; then
               echo "::error file=$f::Lockfile contains 'node_modules/.pnpm/' substring. This means it was authored from inside a pnpm workspace and references parent paths that do not exist in CI. To repair: copy package.json to a directory outside any pnpm workspace, run 'npm install' there, copy the resulting package-lock.json back, commit, push."
@@ -95,7 +95,7 @@ jobs:
         run: npm run build
 
       - name: Install dashboard dependencies
-        run: cd src/cli/dashboard && npm ci
+        run: cd src/dashboard && npm ci
 
       - name: Build dashboard
         run: npm run dashboard:build
@@ -147,7 +147,7 @@ jobs:
           name: build
           path: |
             dist/
-            src/cli/dashboard/dist/
+            src/dashboard/dist/
             docs/api/
             assets/
             scenarios/

README.md

@@ -403,7 +403,7 @@ Numbers assume 6 turns, 5 departments, 100 agents, up to 3 events per turn. Forg
 
 Director event → Kernel advance (deterministic, seeded) → Department analysis in parallel (with optional runtime tool forging in a hardened `node:vm` sandbox; an LLM judge approves each forge) → Commander decision (HEXACO-weighted) → Outcome classification → Kernel effects → Agent reactions → Memory consolidation → Personality drift.
 
-Every structured LLM call (director, departments, commander, reactions, verdict) is Zod-validated with retry-with-feedback. Schemas under [`src/runtime/schemas/`](src/runtime/schemas/). Full per-stage breakdown in [docs/architecture.md](docs/architecture.md).
+Every structured LLM call (director, departments, commander, reactions, verdict) is Zod-validated with retry-with-feedback. Schemas under [`src/runtime/validators/`](src/runtime/validators/). Full per-stage breakdown in [docs/architecture.md](docs/architecture.md).
 
 ---
 

docs/ARCHITECTURE.md

@@ -185,10 +185,10 @@ Each turn follows a fixed pipeline:
 
 Every structured LLM call in paracosm routes through one of two schema-validated wrappers:
 
-- **[`generateValidatedObject`](../src/runtime/llm-invocations/generateValidatedObject.ts)**: one-shot calls over AgentOS `generateObject`. Used for director event batches, reaction batches, verdict.
-- **[`sendAndValidate`](../src/runtime/llm-invocations/sendAndValidate.ts)**: session-aware wrapper over AgentOS `session.send()`. Preserves conversation memory (commander remembers prior events, dept heads remember prior analyses) while adding Zod retry-with-feedback. Used for commander decisions, department reports, and promotions.
+- **[`generateValidatedObject`](../src/llm/generateValidatedObject.ts)**: one-shot calls over AgentOS `generateObject`. Used for director event batches, reaction batches, verdict.
+- **[`sendAndValidate`](../src/llm/sendAndValidate.ts)**: session-aware wrapper over AgentOS `session.send()`. Preserves conversation memory (commander remembers prior events, dept heads remember prior analyses) while adding Zod retry-with-feedback. Used for commander decisions, department reports, and promotions.
 
-Both wrappers return the fully-validated object matching a Zod schema in [`src/runtime/schemas/`](../src/runtime/schemas/). Validation failures trigger up to 2 retries with the Zod error appended to the retry prompt so the model self-corrects. If retries exhaust, the wrapper returns a caller-provided fallback skeleton and emits a `validation_fallback` SSE event so the dashboard can surface the degradation.
+Both wrappers return the fully-validated object matching a Zod schema in [`src/runtime/validators/`](../src/runtime/validators/). Validation failures trigger up to 2 retries with the Zod error appended to the retry prompt so the model self-corrects. If retries exhaust, the wrapper returns a caller-provided fallback skeleton and emits a `validation_fallback` SSE event so the dashboard can surface the degradation.
 
 | Call site | Schema | Wrapper |
 |-----------|--------|---------|
@@ -241,7 +241,7 @@ EmergentJudge        LLM-as-judge safety + correctness review
    │
    ▼
 capture callback     feeds CapturedForge into paracosm's per-dept bucket
-   │                 (paracosm/src/runtime/orchestrator.ts)
+   │                 (paracosm/src/runtime/orchestrator/index.ts)
    ▼
 ForgeStatsAggregator aggregates attempts + classifies rejection reasons
    │                 (source: @framers/agentos/emergent; composed into CostTracker)
@@ -595,7 +595,7 @@ Scope note: v1 replay re-runs `advanceTurn` only. Re-applying recorded decisions
 
 #### HTTP surface
 
-The HTTP surface for replay is `POST /api/v1/runs/:runId/replay` on the dashboard server. The endpoint loads the stored artifact via `record.artifactPath`, looks up the original scenario via the in-memory catalog, constructs a `WorldModel`, calls `WorldModel.replay(artifact)`, and persists the outcome via `runHistoryStore.recordReplayResult(runId, matches)`. Returns `{ matches: boolean, divergence: string }` on 200, structured errors on 404 / 410 / 422. The client-side hook is `src/cli/dashboard/src/components/library/hooks/useReplayRun.ts`.
+The HTTP surface for replay is `POST /api/v1/runs/:runId/replay` on the dashboard server. The endpoint loads the stored artifact via `record.artifactPath`, looks up the original scenario via the in-memory catalog, constructs a `WorldModel`, calls `WorldModel.replay(artifact)`, and persists the outcome via `runHistoryStore.recordReplayResult(runId, matches)`. Returns `{ matches: boolean, divergence: string }` on 200, structured errors on 404 / 410 / 422. The client-side hook is `src/dashboard/src/components/library/hooks/useReplayRun.ts`.
 
 ### Digital-twin subpath (T5.4)
 
@@ -640,32 +640,60 @@ Paracosm uses AgentOS for all agent orchestration, LLM calls, tool forging, and
 | `AgentMemory.sqlite()` | Colonist chat memory with episodic storage and RAG |
 | HEXACO personality | Trait-modulated decision making, memory retrieval, mood adaptation |
 
-## Source Structure
+## Top-level `src/` layout
 
 ```
 src/
-  engine/           the npm package (exported)
-    core/           deterministic kernel (RNG, state, progression, personality drift)
-    compiler/       JSON → ScenarioPackage compiler
-    mars/           Mars Genesis scenario
-    lunar/          Lunar Outpost scenario
-
-  runtime/          orchestration (not exported)
-    orchestrator              turn pipeline: director → kernel → departments → commander
-    director                  emergent crisis generation from simulation state
-    departments               parallel department analysis agents
-    chat-agents               post-simulation colonist chat with AgentOS memory
-    schemas/                  Zod schemas for every structured LLM call
-    llm-invocations/          generateValidatedObject + sendAndValidate wrappers
-    hexaco-cues/              trajectory + reaction cue translation helpers
-
-  cli/              server + dashboard (not exported)
-    serve.ts        HTTP + SSE server
-    pair-runner.ts  parallel leader execution + verdict
-    server-app.ts   all HTTP endpoints
-    dashboard/      React/Vite live visualization
+├── engine/      Scenario kernel + compile-time. Compiler runs ONCE; kernel is deterministic.
+│   ├── core/        deterministic kernel (RNG, state, progression, personality drift)
+│   ├── compiler/    JSON → ScenarioPackage compiler (LLM-driven, runs once)
+│   ├── schema/      foundational types and Zod validators
+│   ├── scenarios/   built-in scenario loaders (mars, lunar)
+│   ├── physics/     physics modules registry
+│   ├── traits/      HEXACO + AI-agent trait registries
+│   ├── presets/     actor presets
+│   ├── provider/    provider key resolution + credentials
+│   ├── digital-twin/  public-API alias barrel for WorldModel as DigitalTwin
+│   ├── data-driven-hooks/
+│   └── registries/  effects, events, metrics
+│
+├── runtime/     Per-turn simulation execution. LLM-driven orchestration.
+│   ├── orchestrator/  turn pipeline (director → kernel → departments → commander → reactions)
+│   ├── agents/        chat-agents, agent-memory, agent-reactions, cues/
+│   ├── world-model/   WorldModel façade (replay, fork, snapshot)
+│   ├── swarm/         pure projections over RunArtifact swarm view
+│   ├── research/      citation/research memory
+│   ├── validators/    Zod validators for LLM responses (commander, department, director, verdict)
+│   ├── economics/     cost-tracker, pricing, economics-profile
+│   ├── io/            output-writer, build-artifact, sse-envelope, citations-catalog, canonical-json, world-snapshot
+│   └── util/          parsers, runtime-helpers, provider-errors, generic-fingerprint
+│
+├── llm/         Shared LLM helpers (generateValidatedObject, sendAndValidate). Imported by engine/compiler and runtime.
+├── api/         Public run/runMany surface. The 90% case for paracosm consumers.
+├── cli/         CLI entry points (run, run-a, run-b, compile, init, serve, help) + scenario-config helpers.
+├── server/      HTTP server. Subdivided into routes/, stores/, services/.
+└── dashboard/   Vite/React UI. Talks to server/ via fetch.
 ```
 
+`engine/` does NOT import `runtime/` (enforced by `scripts/check-engine-runtime-boundary.mjs`, which runs as part of `npm test`). One barrel file is exempt: `src/engine/digital-twin/index.ts`, the public-API alias for `WorldModel as DigitalTwin`.
+
+For the contributor reference (where new code goes, naming conventions, public-export-to-internal-path mapping), see [`architecture/INTERNAL_LAYOUT.md`](architecture/INTERNAL_LAYOUT.md).
+
+## AgentOS API surface used by paracosm
+
+Paracosm depends on a small surface of `@framers/agentos`. Six distinct symbols across eight files:
+
+| Symbol | Used in |
+|---|---|
+| `ITool` (type) | `runtime/orchestrator/index.ts`, `runtime/orchestrator/emergent-setup.ts` |
+| `AgentMemory` (class) | `runtime/agents/chat-agents.ts` |
+| `agent` (factory) | `runtime/agents/chat-agents.ts` |
+| `generateObject` | `llm/generateValidatedObject.ts` |
+| `ObjectGenerationError` | `llm/generateValidatedObject.ts`, `llm/sendAndValidate.ts` |
+| `extractJson` | `llm/sendAndValidate.ts` |
+
+The shared LLM primitives (`generateValidatedObject`, `sendAndValidate`) own four of the six symbols and live in `src/llm/`. Higher-level callers (`runtime/orchestrator/`, `runtime/agents/chat-agents.ts`) import the remaining symbols directly. No paracosm-side adapter layer; the surface is small enough that direct imports are clearer than indirection.
+
 ## References
 
 - Ashton, M. C., & Lee, K. (2007). Empirical, theoretical, and practical advantages of the HEXACO model of personality structure. *Personality and Social Psychology Review*, 11(2), 150-166. [hexaco.org](https://hexaco.org/)

docs/COOKBOOK.md

@@ -870,7 +870,7 @@ Router unit tests live at [`tests/cli/router.test.ts`](../tests/cli/router.test.
 
 ## Pluggable trait models: `ai-agent` end-to-end
 
-paracosm@0.8+ ships a `TraitModel` registry alongside the historical HEXACO. Two built-ins land in v1: `hexaco` (the canonical Ashton-Lee shape, the existing default) and `ai-agent` (a six-axis model designed for AI-system leaders). The registry lives at [`src/engine/trait-models/`](../src/engine/trait-models/) and is demonstrated below with a captured end-to-end run.
+paracosm@0.8+ ships a `TraitModel` registry alongside the historical HEXACO. Two built-ins land in v1: `hexaco` (the canonical Ashton-Lee shape, the existing default) and `ai-agent` (a six-axis model designed for AI-system leaders). The registry lives at [`src/engine/traits/`](../src/engine/traits/) and is demonstrated below with a captured end-to-end run.
 
 ### `ai-agent` axes
 

docs/HTTP_API.md

@@ -2,7 +2,7 @@
 
 The dashboard server (`paracosm dashboard`) exposes a versioned HTTP surface under `/api/v1/*`. The same routes power the React dashboard and any external client. This page documents every endpoint, its request shape, response shape, and status codes.
 
-Source of truth: [`src/cli/server/routes/platform-api.ts`](../src/cli/server/routes/platform-api.ts), [`src/cli/server/routes/public-demo.ts`](../src/cli/server/routes/public-demo.ts), [`src/cli/bundle-routes.ts`](../src/cli/bundle-routes.ts), and [`src/cli/server/library-import-route.ts`](../src/cli/server/library-import-route.ts).
+Source of truth: [`src/server/routes/platform-api.ts`](../src/server/routes/platform-api.ts), [`src/server/routes/public-demo.ts`](../src/server/routes/public-demo.ts), [`src/server/routes/bundle.ts`](../src/server/routes/bundle.ts), and [`src/server/routes/library-import.ts`](../src/server/routes/library-import.ts).
 
 For the SDK (`WorldModel.simulate()`, `WorldModel.batch()`, `WorldModel.intervene()`, etc.) see the [Cookbook](./COOKBOOK.md). This page is the wire-level reference for the HTTP surface only.
 

docs/MIGRATION-v0.9.md

@@ -164,3 +164,23 @@ The v0.8 line accumulated three competing shapes (functional `runSimulation`, OO
 The reviewer flagged the npm download stats (~25k/month at v0.8.719) and recommended a soft break. The maintainer chose a hard break to avoid carrying compatibility shims through what should be a clean v1.0 trajectory. v0.8 stays installable indefinitely; new development happens on v0.9.
 
 If you hit a migration footgun this guide doesn't cover, file an issue at https://github.com/framersai/paracosm/issues — we'll add it to the table above.
+
+## v0.10: internal layout reorganization
+
+The `apps/paracosm/src/` tree was reorganized into seven top-level directories: `engine`, `runtime`, `llm`, `api`, `cli`, `server`, `dashboard`. The published public API (the six subpath exports `paracosm`, `paracosm/core`, `paracosm/compiler`, `paracosm/schema`, `paracosm/swarm`, `paracosm/digital-twin`) is bit-stable. No consumer code changes required.
+
+Internal callers performing deep imports (not supported, but not technically forbidden) may need to adjust:
+
+| Old path | New path |
+|---|---|
+| `paracosm/runtime/llm-invocations/generateValidatedObject` | `paracosm/llm/generateValidatedObject` |
+| `paracosm/runtime/llm-invocations/sendAndValidate` | `paracosm/llm/sendAndValidate` |
+| `paracosm/runtime/schemas/<name>` | `paracosm/runtime/validators/<name>` |
+| `paracosm/runtime/orchestrator` (file) | `paracosm/runtime/orchestrator` (folder; same import name) |
+| `paracosm/cli/dashboard/...` | `paracosm/dashboard/...` |
+| `paracosm/cli/server/...`, `paracosm/cli/*-route` | `paracosm/server/{routes,stores,services}/...` |
+| `paracosm/engine/trait-models` | `paracosm/engine/traits` |
+| `paracosm/engine/physics-modules` | `paracosm/engine/physics` |
+| `paracosm/engine/builtin-scenarios` | `paracosm/engine/scenarios` |
+
+If you import only from the documented public subpaths (six entry points), no change is needed.