docs(paracosm): cover 0.6.0 universal schema + list as ecosystem app

PARACOSM.md
- Rewrite quick-start result reads to use finalState?.metrics and
  forgedTools?.length (old finalState.systems + totalToolsForged removed).
- Add universal result contract section covering RunArtifact, three modes,
  11 primitives, scenarioExtensions escape hatch, JSON Schema export.
- Add subjects and interventions section documenting SubjectConfig and
  InterventionConfig input primitives.
- Rewrite API surface imports to include paracosm/schema and paracosm/compiler.
- Fix broken TypeDoc links (/paracosm/interfaces -> /paracosm/engine/interfaces,
  /paracosm/classes -> /paracosm/engine/classes).
- Add the 17-variant StreamEvent list under HTTP+SSE section.

ECOSYSTEM.md
- Add Paracosm as the lead applications entry with npm badge, feature
  bullets, and live demo link.

Author: jddunn

docs/PARACOSM.md

@@ -35,12 +35,70 @@ const result = await runSimulation(aria, [], {
   onEvent: e => console.log(e.type, e.data?.title),
 });
 
-console.log(result.finalState.systems.population);
-console.log(result.totalToolsForged);
+console.log(result.finalState?.metrics.population);
+console.log(result.forgedTools?.length ?? 0);
 ```
 
 Or run the hosted demo at [paracosm.agentos.sh/sim](https://paracosm.agentos.sh/sim) with zero setup. The demo caps turns, population, and model tier so public access stays affordable; paste your own OpenAI or Anthropic key into Settings to unlock full scope.
 
+## The universal result contract
+
+Every `runSimulation()` call returns a Zod-validated `RunArtifact` exported from the `paracosm/schema` subpath. One shape covers three simulation modes, discriminated on `metadata.mode`:
+
+- `turn-loop`: civilization sims (paracosm's built-in mode). Populates `trajectory.timepoints[]` and `decisions[]` with per-turn specialist notes.
+- `batch-trajectory`: digital-twin simulations (digital-twin). Labeled timepoints over a horizon, populated by external LangGraph-style executors.
+- `batch-point`: one-shot forecasts. Overview and risk flags only, no trajectory.
+
+```typescript
+import { RunArtifactSchema, type RunArtifact } from 'paracosm/schema';
+import { runSimulation } from 'paracosm/runtime';
+
+const artifact: RunArtifact = await runSimulation(leader, [], opts);
+const parsed = RunArtifactSchema.parse(artifact); // optional runtime validation
+
+switch (artifact.metadata.mode) {
+  case 'turn-loop':
+  case 'batch-trajectory':
+  case 'batch-point':
+}
+
+artifact.trajectory?.timepoints?.forEach((tp) => {
+  console.log(tp.label, tp.score?.value, tp.narrative);
+});
+```
+
+The schema exposes 11 content primitives (`RunMetadata`, `WorldSnapshot`, `Score`, `HighlightMetric`, `Timepoint`, `TrajectoryPoint`, `Trajectory`, `Citation`, `SpecialistDetail`, `SpecialistNote`, `RiskFlag`, `Decision`) plus operational types (`Cost`, `ProviderError`). Every primitive carries an optional `scenarioExtensions?: Record<string, unknown>` escape hatch for domain-specific fields that must not pollute the universal shape.
+
+Non-TypeScript consumers generate equivalent types from JSON Schema: `npm run export:json-schema` emits `schema/run-artifact.schema.json` and `schema/stream-event.schema.json`. Python projects use `datamodel-codegen`; any ecosystem with a JSON-Schema code generator adopts cleanly. Full adoption walkthrough at [paracosm/docs/adoption/digital-twin.md](https://github.com/framersai/paracosm/blob/master/docs/adoption/digital-twin.md).
+
+### Subjects and interventions
+
+For simulations built around a single subject (a person, character, organism, vessel) under a counterfactual intervention, `paracosm/schema` exposes `SubjectConfig` and `InterventionConfig` as first-class input primitives. Pass them through `RunOptions` and they carry through to `RunArtifact.subject` and `RunArtifact.intervention` for downstream consumers:
+
+```typescript
+import { SubjectConfigSchema, InterventionConfigSchema } from 'paracosm/schema';
+
+const subject = SubjectConfigSchema.parse({
+  id: 'user-42',
+  name: 'Alice',
+  profile: { age: 34, diet: 'mediterranean' },
+  signals: [{ label: 'HRV', value: 48.2, unit: 'ms', recordedAt: '2026-04-21T08:00:00Z' }],
+  markers: [{ id: 'rs4680', category: 'genome', value: 'AA' }],
+});
+
+const intervention = InterventionConfigSchema.parse({
+  id: 'intv-1',
+  name: 'Creatine + Sleep Hygiene',
+  description: '5g daily + 11pm bedtime.',
+  duration: { value: 12, unit: 'weeks' },
+  adherenceProfile: { expected: 0.7 },
+});
+
+const artifact = await runSimulation(leader, [], { scenario, subject, intervention });
+```
+
+Turn-loop mode stashes both verbatim without semantic consumption; external batch-trajectory executors populate them from their own flow.
+
 ## What it does
 
 Paracosm runs two leaders through the same scenario in parallel and makes their divergence measurable. Each turn has nine stages:
@@ -115,21 +173,33 @@ Users who want more runs paste their own OpenAI or Anthropic key. The dashboard'
 ## API surface
 
 ```typescript
-import type { ScenarioPackage, Agent } from 'paracosm';
+import type { ScenarioPackage, Agent, LeaderConfig, HexacoProfile } from 'paracosm';
+import { SimulationKernel, SeededRng } from 'paracosm';
 import { marsScenario } from 'paracosm/mars';
 import { lunarScenario } from 'paracosm/lunar';
 import { runSimulation, runBatch } from 'paracosm/runtime';
-import { SimulationKernel, SeededRng } from 'paracosm';
+import { compileScenario } from 'paracosm/compiler';
+import {
+  RunArtifactSchema,
+  StreamEventSchema,
+  SubjectConfigSchema,
+  InterventionConfigSchema,
+  type RunArtifact,
+  type StreamEvent,
+  type SubjectConfig,
+  type InterventionConfig,
+} from 'paracosm/schema';
 ```
 
 Full type reference is auto-generated from source at [/paracosm](/paracosm). The core types:
 
-- [`ScenarioPackage`](/paracosm/interfaces/ScenarioPackage) — domain-agnostic scenario bundle
-- [`LeaderConfig`](/paracosm/interfaces/LeaderConfig) — commander identity + HEXACO profile
-- [`HexacoProfile`](/paracosm/interfaces/HexacoProfile) — six-axis personality vector
-- [`SimulationKernel`](/paracosm/classes/SimulationKernel) — deterministic state machine
-- [`runSimulation`](/paracosm/runtime/functions/runSimulation) — single-leader turn loop
-- [`runBatch`](/paracosm/runtime/functions/runBatch) — parallel multi-scenario runner
+- [`ScenarioPackage`](/paracosm/engine/interfaces/ScenarioPackage): domain-agnostic scenario bundle
+- [`LeaderConfig`](/paracosm/engine/interfaces/LeaderConfig): commander identity plus HEXACO profile
+- [`HexacoProfile`](/paracosm/engine/interfaces/HexacoProfile): six-axis personality vector
+- [`SimulationKernel`](/paracosm/engine/classes/SimulationKernel): deterministic state machine
+- [`runSimulation`](/paracosm/runtime/functions/runSimulation): single-leader turn loop, returns `Promise<RunArtifact>`
+- [`runBatch`](/paracosm/runtime/functions/runBatch): parallel multi-scenario runner
+- [`compileScenario`](/paracosm/engine/compiler/functions/compileScenario): turns scenario JSON into a runnable `ScenarioPackage`
 
 ## HTTP + SSE server
 
@@ -148,6 +218,17 @@ The dashboard server exposes a small HTTP API for driving sims from any client:
 
 `/events` replays a buffered event history on reconnect (persisted to disk so restarts do not evaporate completed runs), closes with a `replay_done` marker so clients can distinguish historical from live events.
 
+The SSE stream emits a 17-variant `StreamEvent` discriminated union (defined in `paracosm/schema`), every event carrying a universal `e.data.summary` one-liner so consumers can render cleanly without narrowing on per-event fields:
+
+```
+turn_start, event_start, specialist_start, specialist_done, forge_attempt,
+decision_pending, decision_made, outcome, personality_drift, agent_reactions,
+bulletin, turn_done, promotion, systems_snapshot, provider_error,
+validation_fallback, sim_aborted
+```
+
+Narrow via `e.type` for per-event intellisense on `e.data`. Validate the envelope at runtime with `StreamEventSchema.parse(evt)` when ingesting untrusted streams.
+
 ## Related
 
 - [Emergent Capabilities](/features/emergent-capabilities) — the forge + judge machinery underlying `forge_tool`

docs/architecture/ECOSYSTEM.md

@@ -122,6 +122,26 @@ This is the content package for skills. The runtime engine (SkillLoader, SkillRe
 
 ## Applications
 
+### [Paracosm](https://github.com/framersai/paracosm)
+**AI Agent Swarm Simulation Engine** — Define worlds as JSON, assign AI leaders with HEXACO personality profiles, and watch their decisions compound into measurably different outcomes from identical starting conditions. Built on `@framers/agentos`.
+
+```bash
+npm install paracosm
+```
+
+[![npm](https://img.shields.io/npm/v/paracosm?logo=npm&color=cb3837)](https://www.npmjs.com/package/paracosm)
+[![GitHub](https://img.shields.io/github/stars/framersai/paracosm?style=social)](https://github.com/framersai/paracosm)
+
+**Features:**
+- Universal `RunArtifact` schema at `paracosm/schema` covering turn-loop civilization sims, batch-trajectory digital twins, and batch-point forecasts
+- HEXACO personality-driven commander decisions with runtime tool forging through AgentOS's `EmergentCapabilityEngine`
+- Deterministic kernel: same seed plus same crises equals replayable, diff-able runs
+- `SubjectConfig` and `InterventionConfig` input primitives for digital-twin adoption
+
+🌐 **Live demo:** [paracosm.agentos.sh](https://paracosm.agentos.sh) · **Docs:** [paracosm.agentos.sh/docs](https://paracosm.agentos.sh/docs)
+
+---
+
 ### [agentos.sh](https://github.com/framersai/agentos.sh)
 **Documentation Website** — Official documentation and marketing site.
 
@@ -157,7 +177,7 @@ npm install wunderland
 | Resource | Link |
 |----------|------|
 | Documentation | [agentos.sh/docs](https://agentos.sh/docs) |
-| API Reference | [agentos-live-docs branch](https://github.com/framersai/agentos/tree/agentos-live-docs) |
+| API Reference | [docs.agentos.sh/api](https://docs.agentos.sh/api/) |
 | npm | [@framers/agentos](https://www.npmjs.com/package/@framers/agentos) |
 | Discord | [Join Community](https://discord.gg/usEkfCeQxs) |
 | Twitter | [@framersai](https://twitter.com/framersai) |