Merge pull request #2 from loopengine/positioning/phase-1-runtime-home-readme

docs(readme): Phase 1 — align OSS README with runtime platform

Author: betterdataco

README.md

@@ -1,37 +1,61 @@
 # Loop Engine
 
-> Open runtime for governed, observable enterprise loops.
+> An open governed operational runtime platform for AI-assisted enterprise systems.
 
 [![npm](https://img.shields.io/npm/v/@loop-engine/sdk.svg?label=@loop-engine/sdk)](https://www.npmjs.com/package/@loop-engine/sdk)
 [![Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)
 [![loopengine.io](https://img.shields.io/badge/docs-loopengine.io-blue)](https://loopengine.io)
 
 ## What is Loop Engine?
 
-Loop Engine is an open runtime for governing decisions made by AI agents, humans, and automations working together.
+Loop Engine is an open governed operational runtime platform for AI-assisted enterprise systems.
+
+Loop Engine connects AI providers, communication channels, and enterprise systems through decision loops.
 
 Every transition through a loop:
+
 - Names the actor responsible (human, automation, or AI agent)
 - Evaluates guard policies before allowing the action
-- Attaches structured evidence - what information the actor used
+- Attaches structured evidence — what information the actor used
 - Emits an immutable event with full attribution
 
 This creates a decision record produced at runtime, not reconstructed afterward.
 
-## Why Loop Engine?
+## What exists today
+
+Loop Engine is an **OSS operational substrate** you run in your environment — local-first, developer-operable, governance-native.
+
+| Capability | Status |
+| --- | --- |
+| Decision loop runtime (`@loop-engine/sdk`, `@loop-engine/runtime`) | Shipped |
+| Guards, actors, events, signals (core primitives) | Shipped |
+| Provider adapters (Anthropic, OpenAI, Gemini, Grok, Perplexity tool path) | Shipped |
+| Persistence adapters (memory, Postgres, Kafka) | Shipped |
+| Routing / human surfaces (OpenClaw, PagerDuty, Vercel AI SDK patterns) | Shipped |
+| Observability timelines and replay | Shipped |
+
+Install one SDK entrypoint, add adapters for your stack, define loops in YAML or TypeScript. Full taxonomy and guides live on **[loopengine.io](https://loopengine.io)** — the canonical documentation surface for this runtime.
 
-AI systems make recommendations. Humans approve decisions. Workflows execute actions. But who governed what happened in between?
+## Why Loop Engine?
 
-Loop Engine sits between AI reasoning and operational execution. It enforces who can do what, under what conditions, with what evidence.
+AI systems make recommendations. Humans approve on channels they already use. Enterprise systems execute side effects. Loop Engine governs what happens between them — who may transition, under which guards, with what evidence.
 
 ```text
-AI Agent
+Providers (intelligence)
+   ↓
+Decision loops + guards
+   ↓
+Channels (human surfaces)
    ↓
-Loop Engine    ← decision governance
+Integrations (enterprise systems)
    ↓
-Workflow / ERP / Infrastructure
+Evidence + learning
 ```
 
+Loop Engine is **not** a workflow engine, Slack bot, or generic integration platform. It is governance substrate for AI-assisted operations.
+
+**Workflows define the path. Loops govern the transitions.** Durable orchestrators (Temporal, n8n, application code) may execute approved work; Loop Engine decides whether state may change and records evidence first.
+
 ## Quick Start
 
 ```bash
@@ -94,63 +118,55 @@ await engine.transition({
 })
 ```
 
-## Packages
-
-| Package | Description |
-|---|---|
-| [`@loop-engine/sdk`](packages/sdk) | Main SDK - start here |
-| [`@loop-engine/runtime`](packages/runtime) | Loop lifecycle and transitions |
-| [`@loop-engine/observability`](packages/observability) | Timeline and replay |
-| [`@loop-engine/adapter-memory`](packages/adapter-memory) | In-memory storage |
-| [`@loop-engine/adapter-postgres`](packages/adapters/postgres) | PostgreSQL storage |
-| [`@loop-engine/adapter-kafka`](packages/adapters/kafka) | Kafka event streaming |
-| [`@loop-engine/adapter-anthropic`](packages/adapter-anthropic) | Claude AI actor |
-| [`@loop-engine/adapter-openai`](packages/adapter-openai) | OpenAI AI actor |
-| [`@loop-engine/adapter-grok`](packages/adapter-grok) | Grok (xAI) AI actor |
-| [`@loop-engine/adapter-gemini`](packages/adapter-gemini) | Gemini AI actor |
-| [`@loop-engine/adapter-perplexity`](packages/adapter-perplexity) | Perplexity Sonar (`ToolAdapter`, citations) |
-| [`@loop-engine/adapter-openclaw`](packages/adapter-openclaw) | OpenClaw integration |
-| [`@loop-engine/adapter-commerce-gateway`](packages/adapter-commerce-gateway) | Commerce Gateway |
-| [`@loop-engine/adapter-pagerduty`](packages/adapter-pagerduty) | PagerDuty incidents |
-| [`@loop-engine/adapter-vercel-ai`](packages/adapter-vercel-ai) | Vercel AI SDK |
-
-Core primitives are bundled in `@loop-engine/sdk`. Internal monorepo-only packages for contributors are:
-`core`, `dsl`, `guards`, `actors`, `events`, and `signals`.
+## npm packages (implementation layer)
+
+`@loop-engine/*` packages implement the runtime — start with [`@loop-engine/sdk`](packages/sdk). Adapters are optional by surface:
+
+| Layer | Packages |
+| --- | --- |
+| Runtime core | `sdk`, `runtime`, `guards`, `actors`, `events`, `signals` |
+| Providers | `adapter-anthropic`, `adapter-openai`, `adapter-gemini`, `adapter-grok`, `adapter-perplexity` |
+| Channels / routing | `adapter-openclaw`, `adapter-vercel-ai`, `adapter-pagerduty` |
+| Integrations | `adapter-postgres`, `adapter-kafka`, `adapter-http`, `adapter-commerce-gateway`, `adapter-memory` |
+
+Contributor-only monorepo packages: `core`, `dsl`, and related internals bundled through `sdk` for app developers.
 
 ## Documentation
 
-Full docs at **[loopengine.io](https://loopengine.io)**
+**Canonical documentation:** **[loopengine.io/docs](https://loopengine.io/docs)** — runtime model, taxonomy, examples, and self-host paths. This repository README is a GitHub entrypoint; do not treat the package table above as the product story.
 
 - [Quick Start](https://loopengine.io/docs/getting-started/quick-start)
-- [Core Concepts](https://loopengine.io/docs/core-concepts)
-- [Examples](https://loopengine.io/docs/examples)
+- [Architecture](https://loopengine.io/docs/getting-started/architecture)
 - [Integrations](https://loopengine.io/docs/integrations)
-- [Perplexity Sonar & Computer (OSS)](docs/integrations-perplexity.md)
+- [Examples](https://loopengine.io/docs/examples)
 
-## Examples
+## Loop Engine Cloud (hosted boundary)
+
+**Loop Engine** (this repo) is the open runtime you self-host.
 
-Runnable examples in [github.com/loopengine/loop-examples](https://github.com/loopengine/loop-examples):
+**Loop Engine Cloud** is Better Data’s hosted governance control plane — multi-tenant runtime, connectors, and API keys at [loops.betterdata.co](https://loops.betterdata.co). Contract and operational details: [loopengine.io/docs/integrations/loop-engine-cloud-api](https://loopengine.io/docs/integrations/loop-engine-cloud-api).
 
-- Expense Approval - human-only approval gate
-- AI Replenishment - Claude + OpenAI as governed actors
-- Demand Signal - rule-based loop triggering
-- Postgres Persistence - production storage adapter
-- Event Streaming - Kafka event pipeline
+We do not claim feature parity between every OSS adapter and Cloud connectors in this README; see hosted docs for what is available in your tenant.
+
+## Platform direction
+
+Roadmap themes (not delivery commitments): richer runtime taxonomy docs on loopengine.io, expanded channel adapters, and deeper hosted connector coverage. We avoid promising undelivered surfaces (e.g. multi-service compose stacks or studio products) in OSS copy — direction is shared on [loopengine.io/changelog](https://loopengine.io/docs/changelog) and GitHub discussions.
+
+## Examples
+
+Reference walkthroughs on [loopengine.io/docs/examples](https://loopengine.io/docs/examples). The [loop-examples](https://github.com/loopengine/loop-examples) repository is being brought up to match current SDK APIs — verify runnable status before citing copy-paste flows.
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). Open issues and RFCs at [github.com/loopengine/loop-engine/discussions](https://github.com/loopengine/loop-engine/discussions).
+See [CONTRIBUTING.md](CONTRIBUTING.md). RFCs and discussions: [github.com/loopengine/loop-engine/discussions](https://github.com/loopengine/loop-engine/discussions).
 
-## Provenance and package trust
+## Provenance
 
 - **Canonical repository:** https://github.com/loopengine/loop-engine
-- **Maintainer organization:** Better Data, Inc. (https://betterdata.co)
-- **Package family:** `@loop-engine/*` packages in `packages/`
-- **Issue tracker:** https://github.com/loopengine/loop-engine/issues
-- **Documentation site:** https://loopengine.io
+- **Maintainer:** Better Data, Inc. — https://betterdata.co
+- **Documentation:** https://loopengine.io
+- **Issues:** https://github.com/loopengine/loop-engine/issues
 
 ## License
 
-Apache-2.0 - see [LICENSE](LICENSE) for details.
-
-Created and maintained by [Better Data](https://betterdata.co).
+Apache-2.0 — see [LICENSE](LICENSE).