docs: expand SDK README

README.md

@@ -1,22 +1,192 @@
-# Matrix SDK Workspace
+# Matrix SDK
 
-This workspace is the isolated SDK incubation area for
+Matrix SDK is the package-author layer for building Matrix actors, browser
-`WORKSTREAMS/matrix-sdk-isolation`.
+surfaces, and broker-connected applications without depending on the HiveCast
+platform repo.
 
-Current proven checkpoints:
+This repository contains the SDK packages that were split out of Matrix-3 and
+renamed to their publishable `@open-matrix/*` package names. The split is
+proven as a standalone workspace: a fresh clone can install, build, test,
+type-check, pack every package, and compile an external consumer against the
+packed tarballs.
 
-- copied SDK-bearing packages build/test/type-check/pack independently
+## What You Can Build
-- copied package identities were renamed to final `@open-matrix/*` names
-- `@open-matrix/sdk` facade package builds/tests/packs
-- `@open-matrix/browser-kit` builds package-manager-ready `dist` exports
-- a fresh external temp consumer installs packed tarballs, compiles, starts a
-  `MatrixActor`, and calls it through the Matrix runtime/transport path
 
-Proof commands:
+- Headless actors with `MatrixActor`
+- Browser custom elements with `MatrixActorHtmlElement`
+- In-memory actor graphs for tests and local development
+- NATS-backed transports for broker-connected actors
+- Browser host integrations for Matrix web surfaces
+- Package-author CLIs and project scaffolds
 
-```bash
+Matrix SDK is provider-neutral. It does not require HiveCast, Device Link, Host
-pnpm --dir projects/matrix-sdk prove
+Link, Host Service, or a local HiveCast install. HiveCast is one managed provider
-pnpm --dir projects/matrix-sdk prove:external-consumer
+that can issue broker credentials and host runtimes on top of the SDK.
+
+## Packages
+
+| Package | Purpose |
+| --- | --- |
+| `@open-matrix/sdk` | Public umbrella facade for actor/package authors |
+| `@open-matrix/core` | Actor kernel, runtime, transports, serialization, browser actor base classes |
+| `@open-matrix/cli` | Package-author `matrix` CLI |
+| `@open-matrix/browser-kit` | Browser app shims, theme tokens, Vite helpers, shell components |
+| `@open-matrix/browser-host` | Browser runtime host shell and app-ready integration |
+| `@open-matrix/contracts` | Shared type contracts for placement, service registry, and runtime presence |
+| `@open-matrix/federation` | Cross-realm messaging, MX envelope handling, and routing helpers |
+| `@open-matrix/omega-core` | Narrow Omega interpreter facade used by Matrix membranes |
+
+Prefer narrow imports when possible:
+
+```ts
+import { MatrixActor } from '@open-matrix/core';
 ```
 
-Matrix-3 consumers have not been repointed yet.
+Use the umbrella package when you intentionally want the public SDK facade:
+
+```ts
+import { MatrixActor } from '@open-matrix/sdk';
+```
+
+## Quick Start
+
+```bash
+git clone git@github.com:matrix-sdk/matrix-sdk.git
+cd matrix-sdk
+pnpm install --frozen-lockfile
+pnpm prove
+```
+
+`pnpm prove` runs the standalone proof:
+
+```text
+clean -> build -> test -> type-check -> pack all packages
+```
+
+For the external-consumer proof:
+
+```bash
+pnpm prove:external-consumer
+```
+
+That proof packs the SDK packages, creates a temporary consumer outside this
+repo, installs the packed tarballs, compiles TypeScript, starts a `MatrixActor`,
+and calls it through the Matrix runtime/transport path.
+
+## Minimal Actor
+
+```ts
+import {
+  InMemoryBroker,
+  InMemoryTransport,
+  MatrixActor,
+  MatrixRuntime,
+  TopicRouter,
+} from '@open-matrix/core';
+
+class EchoActor extends MatrixActor {
+  static accepts = {
+    echo: {},
+  };
+
+  onEcho(payload: { message?: string }) {
+    return {
+      ok: true,
+      message: payload.message ?? null,
+    };
+  }
+}
+
+const broker = new InMemoryBroker();
+const transport = new InMemoryTransport(broker, { name: 'demo' });
+const runtime = new MatrixRuntime({ transport, logging: false });
+
+await runtime.create(EchoActor, 'demo.echo');
+
+const replyTo = '$replies.demo';
+const response = new Promise((resolve) => {
+  const unsubscribe = transport.subscribe(replyTo, (value) => {
+    unsubscribe();
+    resolve(value);
+  });
+});
+
+transport.publish(TopicRouter.inbox('demo.echo'), {
+  op: 'echo',
+  payload: { message: 'hello' },
+  replyTo,
+  correlationId: 'demo-1',
+});
+
+console.log(await response);
+await runtime.shutdown();
+```
+
+## CLI
+
+The SDK CLI package owns the package-author `matrix` binary.
+
+```bash
+matrix init [dir]
+matrix add actor <name>
+matrix actor <name>
+matrix configure --key <key> --cloud <url> --space <space>
+matrix run <entry> --mount <mount>
+matrix invoke <mount> <op> [json]
+```
+
+The current CLI proof is:
+
+```bash
+pnpm prove:cli-uat
+```
+
+The CLI is intended to let a package author initialize a folder, add actors,
+configure broker access, run actors, and invoke them without importing HiveCast
+product packages into the SDK layer.
+
+## Repository Layout
+
+```text
+packages/
+  browser-host/
+  browser-kit/
+  cli/
+  contracts/
+  core/
+  federation/
+  omega-core/
+  sdk/
+scripts/
+  prove-external-consumer.mjs
+  prove-sdk-cli-uat.mjs
+```
+
+## Current Status
+
+Done and proven:
+
+- The SDK packages build independently from Matrix-3.
+- Package identities use final `@open-matrix/*` names.
+- `@open-matrix/sdk` re-exports the public actor facade.
+- A fresh clone passes `pnpm install --frozen-lockfile && pnpm prove`.
+- A temporary external consumer can install packed SDK tarballs, compile, start
+  a `MatrixActor`, and call it through Matrix runtime/transport.
+
+Still planned:
+
+- Provider-neutral credential resolution for `matrix configure` and SDK users.
+- `matrix login --provider hivecast` to write the same config shape as
+  `matrix configure`.
+- Direct broker mode with explicit broker URL/JWT/seed credentials.
+- HiveCast provider mode where HiveCast issues scoped broker credentials.
+- Publishing the packages to npm after the provider-login contract is complete.
+
+## Relationship To HiveCast
+
+Matrix SDK is the open, provider-neutral actor SDK.
+
+HiveCast is a managed overlay on top of Matrix SDK. HiveCast can provide account
+management, Spaces, API keys, broker credential issuance, runtime hosting,
+package distribution, and operator UI. SDK users should still be able to connect
+to another broker directly when they already manage their own broker credentials.