surface-matrix.md

OpenRustClaw Surface Matrix

This is the source-backed surface inventory for the current self-hosted OpenRustClaw product.

It maps the declared shipped feature families to the current implementation state, owning code, representative tests, local docs, and the severity of the remaining delivery gap. Use it with docs-audit.md and documentation-contract.md when reviewing whether the docs and runtime still tell the same story.

Reviewed against the current shipped OpenRustClaw surface on 2026-03-25.

Status Keys

• matched: shipped and usable end to end.
• partial: exists, but operators would still notice gaps.
• gated: present in the repo, but intentionally not part of the shipped surface.
• missing: no meaningful shipped path exists yet.
• stronger-divergence: OpenRustClaw intentionally differs and is stronger in a meaningful way.
• out-of-scope: intentionally not part of the current shipped target.

Scope Keys

• core: part of the shipped target surface.
• plugin: extension/plugin target surface.
• divergence: intentional product difference to preserve.
• out-of-scope: explicitly not in the near-term shipped target.

Matrix

Feature family	Shipped surface	Scope	ORC status	Owner	Representative tests	Local docs	Gap severity	Notes / next slice
Gateway process	Single gateway process as source of truth for sessions, routing, and channel connections	core	matched	crates/gateway, crates/cli, crates/agent	tests/e2e/tests/vertical/test_gateway_layer.rs, tests/integration/src/gateway_test.rs, scripts/check-runtime-budgets.sh	README.md, docs/src/architecture/overview.md, docs/src/deployment/docker.md, docs/src/deployment/production.md	low	Core runtime exists and is usable end to end, the shipped production Docker/Compose path is now Rust-owned instead of bundling the optional compatibility sidecar into the default runtime image, and the release lane now includes scripted artifact packaging plus bounded binary-size/startup/RSS regression checks
Multi-agent routing	Isolated sessions per agent, sender, workspace, and bindings	core	matched	crates/cli/src/commands/start.rs, crates/core, crates/agent, crates/cli/src/commands/channels.rs	tests/e2e/src/test_chat_workflow.rs, tests/e2e/src/test_security_workflow.rs, crates/cli/src/commands/start.rs unit tests	docs/roadmap.md, docs/feature-matrix.md	medium	Shipped runtime now applies workspace/account/channel binding precedence and stores bound route metadata; richer multi-agent UX remains follow-on work
Session tools	Inspect, create, route, and manage sessions from operator surfaces and tools	core	matched	crates/gateway/src/sessions.rs, crates/db/src/session_store.rs, crates/cli/src/commands/session.rs, crates/cli/src/commands/start.rs	crates/cli/src/commands/start.rs unit tests, cargo test -p openrustclaw-cli, cargo test -p openrustclaw-integration-tests --quiet, tests/integration/src/fixture_suite_test.rs	docs/roadmap.md, README.md, docs/src/contributing/testing.md	low	Durable sessions, persisted history, CLI controls, and MCP tools are now real
Direct vs group session policy	Direct chats can collapse into main; groups isolate; thread scope can override channel scope	core	matched	crates/cli/src/commands/start.rs, crates/core/src/config.rs, config/default.toml	crates/cli/src/commands/start.rs unit tests	docs/roadmap.md, docs/feature-matrix.md	low	Session-routing policy is now explicit and configurable for direct/group/thread scope
Streaming and chunking	Preview streaming, block streaming, coalescing, pacing	core	matched	crates/cli/src/commands/start.rs, crates/channels	crates/cli/src/commands/start.rs unit tests	docs/src/operations/observability.md, docs/roadmap.md	medium	Shipped channel runtime now expands outbound replies through preview/block/coalescing/pacing policy before channel delivery
WhatsApp	WhatsApp Web / pairing / group routing / media	core	matched	crates/channels/src/whatsapp.rs, crates/cli/src/commands/whatsapp.rs, crates/cli/src/main.rs	cargo test -p openrustclaw-channels whatsapp, cargo test -p openrustclaw-cli whatsapp	README.md, docs/feature-matrix.md, docs/roadmap.md, crates/channels/README.md	medium	Shipped runtime now covers pairing/QR, CLI operator flows, DM/group routing, mentions, replies, media send/receive, delivery acknowledgement handling, and local agent/session routing
Telegram	Bot auth, send/receive, routing	core	matched	crates/channels/src/telegram.rs, crates/cli/src/commands/start.rs	crates/channels/src/telegram.rs, cargo test -p openrustclaw-channels telegram	README.md, docs/feature-matrix.md	low	Current tier-1 shipped path is real
Discord	Interactions, gateway message ingress, replies, threads, routing	core	matched	crates/channels/src/discord.rs, crates/cli/src/commands/start.rs	cargo test -p openrustclaw-channels discord	README.md, docs/feature-matrix.md, docs/roadmap.md, crates/channels/README.md	medium	Shipped runtime now covers Interactions ingress, gateway lifecycle handling, thread-aware routing, local file uploads, forwarded-attachment downloads, reply/reference semantics, and local agent/session routing
iMessage	Local bridge, send/receive, attachments	core	matched	crates/channels/src/imessage.rs, crates/cli/src/commands/imessage.rs, crates/cli/src/main.rs, crates/cli/src/commands/start.rs	cargo test -p openrustclaw-channels imessage, cargo test -p openrustclaw-cli imessage	README.md, docs/feature-matrix.md, docs/roadmap.md, crates/channels/README.md	medium	Shipped runtime now covers BlueBubbles/macOS direct send, webhook ingress, tapbacks, chat/participant mapping, attachment handling, CLI operator flows, and local agent/session routing
Mattermost plugin channel	Plugin-based channel extension	divergence	stronger-divergence	crates/channels/src/mattermost.rs, crates/cli/src/commands/start.rs	tests/integration/src/channel_fixture_test.rs, tests/integration/src/documented_scenario_test.rs	docs/roadmap.md, docs/product-positioning.md, docs/feature-matrix.md	low	OpenRustClaw ships Mattermost as a first-class Rust channel, and the extensibility lane is the compiled-skill channel-extension/background-service contract rather than a second channel plugin runtime
Slack / extra operator channels	Slack and additional channel accounts via CLI	core	matched	crates/channels/src/slack.rs, crates/cli/src/commands/channels.rs, crates/cli/src/commands/start.rs, crates/cli	cargo test -p openrustclaw-channels slack, crates/cli/src/commands/channels.rs, crates/cli/src/commands/start.rs unit tests	README.md, docs/feature-matrix.md, docs/roadmap.md, crates/channels/README.md	medium	Slack runtime is now complete for the declared shipped surface, and channel account/binding management is separately matched through the file-backed channel registry and CLI controls
Media support	Images, audio, and documents in and out	core	matched	crates/channels, crates/gateway, crates/automation, crates/cli/src/commands/media.rs	channel-specific coverage in cargo test -p openrustclaw-channels, plus CLI channel tests where shipped, cargo test -p openrustclaw-integration-tests --quiet, tests/integration/src/fixture_suite_test.rs	README.md, docs/roadmap.md, docs/feature-matrix.md, docs/src/contributing/testing.md	medium	Media/file-reference send and receive flows are now complete for the declared shipped channel surface; the operator lane now also has bounded media provider/readiness inspection with summary counts, bounded local image/document inspection, OCR-backed or provider-backed bounded image text extraction, provider-backed bounded image description plus bounded document/audio summaries over the shipped Anthropic plus Gemini plus Ollama plus OpenAI-compatible providers, and bounded local-audio text extraction over the shipped STT providers
Voice-note transcription	Provider-backed audio transcription in message flows	core	matched	crates/cli/src/commands/voice.rs, crates/cli/src/commands/voice_runtime.rs, crates/cli/src/commands/talk.rs, crates/cli/src/commands/start.rs, crates/core/src/config.rs, crates/voice	cargo test -p openrustclaw-cli voice_runtime, cargo test -p openrustclaw-cli start, cargo test -p openrustclaw-cli --quiet	README.md, docs/roadmap.md, docs/feature-matrix.md	high	The shipped runtime now covers provider-backed inbound voice-note transcription for supported channel attachments, transcript injection into message flows, CLI/API/UI inspection and ad hoc transcription, explicit provider catalog/readiness for OpenAI-compatible STT/TTS lanes plus a bounded Deepgram STT lane, bounded persisted voice-session receipts with indexed transcript visibility plus synthesized output artifact inspection, derived event timelines, derived session and aggregate metrics, health/reap/prewarm/reconnect controls over the same STT/TTS providers, a bounded talk/wake receipt lane through `talk-runtime status
Web Control UI	Browser dashboard for chat, config, sessions, and nodes	core	matched	crates/cli/src/commands/start.rs, crates/cli/src/commands/control_ui.rs	cargo test -p openrustclaw-cli, mdbook build docs	docs/roadmap.md, docs/product-positioning.md, docs/feature-matrix.md	low	The shipped /control/ui now covers the declared browser-based operator surface for runtime/config/channels/orchestration/browser/skills inspection, service status, scheduler health, persisted runtime-health inspection with degraded-mode warnings, runtime liveness-beacon and reload-plan inspection, enabled-channel readiness, recent runtime events, live runtime logs, sessions, memory, jobs, config validate/apply, vault key editing, autonomy-policy and decision-lesson inspection/curation, extension discovery plus install/update/uninstall/verify management, mobile/node inspection via the same typed control APIs, active orchestration watch/pause/resume/kill control, orchestration run supervision detail, reflection-candidate promotion, orchestration trace/transcript plus delegation-relationship inspection, orchestration resource summaries, and live diagnostics; interactive live chat remains intentionally CLI/MCP-first rather than a separate browser requirement
Mobile nodes	iOS/Android nodes, pairing, Canvas, device commands	core	matched	crates/mobile, crates/mobile/src/protocol.rs, crates/cli/src/commands/mobile.rs, crates/cli/src/commands/start.rs, crates/cli/src/commands/control_ui.html	cargo test -p openrustclaw-cli mobile, cargo test -p openrustclaw-cli --quiet, cargo test -p openrustclaw-integration-tests --quiet, tests/integration/src/fixture_suite_test.rs	README.md, docs/feature-matrix.md, docs/roadmap.md, docs/src/contributing/testing.md	critical	File-backed mobile node manifests plus CLI/API/UI operator surfaces now exist for node inspection, readiness derivation, pairing/unpair lifecycle receipts plus pairing-history inspection, message/notification previews, sync-readiness previews, bounded capability inventory, bounded capability previews plus execution receipts for camera/screen/location/photos/contacts/calendar/canvas/SMS-style lanes, and a bounded approval-gated device-command lane with persisted receipts, ephemeral execution for the shipped command set, and a shared typed Rust mobile command protocol; the shipped control plane now also persists mobile runtime receipts, derived app-session lifecycle receipts, bounded app-session metrics and event timelines, heartbeat updates, bounded wake/rehydrate requests for disconnected nodes, bounded push-registration plus sync-state reporting, bounded sync-conflict receipts with operator resolution, bounded mobile notification plus inbound/outbound message receipts with acknowledgement, bounded media-artifact receipts for the shipped capture-style capability lanes, bounded per-node activity timelines, and bounded mobile metrics/per-node summary surfaces
Onboarding wizard	Guided setup and service install	core	matched	crates/cli/src/commands/onboard.rs, crates/cli	CLI parsing tests in crates/cli/src/main.rs, cargo test -p openrustclaw-cli onboard --quiet	README.md, docs/roadmap.md	low	onboard now detects existing workspace state, supports keep/modify/reset-with-backup choices, offers QuickStart vs Advanced flows, covers local gateway versus remote-guidance setup, writes the bootstrap .env state, reuses the shared host user-service installer across user-level systemd and launchd, persists provider/control-plane defaults, and finishes with a doctor-backed health handoff; deeper per-channel credential UX remains a polish concern because the shipped channel account flows also exist through the dedicated operator commands
Channel account management	channels add, pairing approve, account-scoped routing	core	matched	crates/cli/src/commands/channels.rs, crates/cli/src/commands/start.rs	crates/cli/src/commands/channels.rs, crates/cli/src/commands/start.rs, cargo test -p openrustclaw-integration-tests --quiet, tests/integration/src/channel_fixture_test.rs	docs/roadmap.md, docs/feature-matrix.md, docs/src/contributing/testing.md	medium	File-backed .claw/channels/ manifests plus CLI controls now cover init/list/approve/block/activation/bind and runtime account-scoped routing
Memory system	Core/recall/archive memory with search and maintenance	core	matched	crates/db, crates/memory, crates/gateway	tests/e2e/src/test_memory_workflow.rs, tests/e2e/tests/regression/test_memory_recall.rs	README.md, docs/src/guides/memory.md, docs/feature-matrix.md	low	Strong practical shipped coverage, with Rust-owned durability
RAG and context	Retrieved context, budgeting, stable source handling	core	matched	crates/db, crates/gateway, crates/memory, crates/agent, crates/cli	sidecar/test_sidecar.py, gateway/RAG tests, cargo test --workspace	README.md, docs/feature-matrix.md, docs/roadmap.md	low	Rust-owned retrieval, budgeting, artifact-aware prompt assembly, memory timelines, and operator inspection are now integrated end to end
Plugin agent tools	Plugin-provided tool surface exposed to agent runs	plugin	matched	crates/skills, crates/mcp, crates/agent, crates/cli/src/commands/start.rs, crates/cli/src/commands/skills.rs, crates/scheduler	crates/skills/src/loader.rs, crates/skills/src/compiler.rs, crates/skills/src/extension.rs, crates/skills/src/runtime.rs, crates/skills/src/sandbox.rs, crates/cli/src/commands/start.rs, crates/cli/src/commands/skills.rs, crates/scheduler/src/workflow.rs	docs/src/guides/skills.md, docs/roadmap.md, docs/src/guides/mcp-servers.md	low	The declared plugin-agent surface is now shipped: compiled help/schema caches emit MCP/CLI-ready artifacts, the built-in MCP server exposes live compiled-skill summary/detail/reference tools plus dynamic `skill..execute
Skills / extension runtime	Signed extension lifecycle, capability gating, safe execution	divergence	stronger-divergence	crates/skills, crates/security	crates/skills/src/loader.rs, crates/skills/src/compiler.rs, crates/skills/src/extension.rs, crates/skills/src/sandbox.rs, crates/security/src/skill_verifier.rs	README.md, docs/src/guides/skills.md, docs/product-positioning.md	low	Intentional stronger Rust-native capability enforcement plus compiled skill artifacts, explicit extension manifests, and scan-aware activation states
Provider auth extensions	Provider auth integrations such as OAuth-backed providers	core	matched	crates/providers, crates/security/src/sso, crates/cli/src/commands/skills.rs, crates/cli/src/commands/start.rs	cargo test -p openrustclaw-cli skills --quiet, cargo test -p openrustclaw-cli start --quiet, provider tests and security tests	README.md, docs/src/guides/skills.md, docs/roadmap.md	low	The shipped auth-plugin lane now covers the declared provider-auth surface through file-backed auth bindings, OIDC authorize/code-exchange flows, callback handling, runtime-vault token persistence, and shared CLI/HTTP/UI surfaces; broader provider-native UX and non-OIDC expansion are optional product choices
Security and pairing controls	Tokens, allowlists, origin checks, pairing approval, safety controls	core	matched	crates/security, crates/gateway, crates/channels, crates/cli	tests/e2e/src/test_security_workflow.rs, tests/integration/src/security_test.rs, tests/integration/src/channel_fixture_test.rs, crates/cli/src/commands/start.rs unit tests, crates/cli/src/commands/channels.rs unit tests	README.md, SECURITY.md, docs/src/guides/security.md, docs/src/contributing/testing.md	medium	Security posture remains strong and shipped tier-1 channels now share a common pairing-approval gate through the file-backed channel registry, while channel account and binding agent_id restrictions are now validated against the control claw registry before operator writes land; the typed /control/... operator surface now also has an opt-in bearer-token gate via security.control_api_token_env, with Control UI forwarding that token to its HTTP and WebSocket calls, reverse-proxy deployments can use an opt-in trusted proxy secret via security.trusted_proxy_token_env for the gateway WebSocket lane plus /control/... surfaces without weakening the default direct bearer/origin checks, browser-origin requests to /control/... and /control/ui now reuse the configured gateway origin allowlist when security.origin_validation is enabled, gateway deployment mode is now explicit through `gateway.network_mode = loopback
Local tool profiling	Probe local CLIs, persist tool profiles, and generate host startup bundles	core	matched	crates/cli/src/commands/tools.rs, crates/cli/src/main.rs, crates/cli/src/commands/start.rs	crates/cli/src/commands/tools.rs, cargo test -p openrustclaw-cli tools --quiet, cargo check -p openrustclaw-cli --quiet	README.md, docs/src/guides/tools.md, docs/src/api-reference/cli.md	low	The shipped operator surface now includes `openrustclaw tools setup
MCP operator surface	MCP server and MCP-friendly tool access	divergence	stronger-divergence	crates/mcp, crates/mcp2cli, crates/cli	tests/integration/src/mcp_test.rs, cargo test -p openrustclaw-cli mcp_server	README.md, docs/src/guides/mcp-servers.md, docs/product-positioning.md	low	OpenRustClaw is intentionally stronger here than the minimum shipped operator contract requires
Observability and evals	Traces, diagnostics, runtime visibility	core	matched	crates/observability, crates/gateway, crates/cli, sidecar	sidecar/test_sidecar.py, observability crate tests, cargo test -p openrustclaw-gateway --quiet, cargo test -p openrustclaw-cli runtime --quiet	docs/src/operations/observability.md, docs/feature-matrix.md	low	Major paths are traced, and shipped service/scheduler/runtime-event, enabled-channel readiness, persisted channel-health monitor state, recent/live runtime-log inspection, active orchestration watch state, and orchestration transcript/resource inspection now exists over CLI, HTTP, and /control/ui; openrustclaw start now exposes a real Prometheus /metrics scrape surface, the shared observability helper API emits real dimensional metrics for the shipped HTTP/provider/agent/memory/cache/database/scheduler/security categories, gateway websocket auth/origin validation plus webhook rate-limit decisions surface through Prometheus, channel ingress plus outbound sends plus scheduler workflow/job runs emit shipped metrics alongside media processing plus compiled-skill/plugin execution plus mobile/node command mutations, the Rust-owned memory-maintenance endpoints emit real maintenance counters/histograms, the shipped CLI/runtime path exports spans to OTLP when OPENRUSTCLAW_OTLP_ENDPOINT or OTEL_EXPORTER_OTLP_ENDPOINT is configured, runtime health persists distinct control-plane provider/fallback roles with configured-model availability checks plus auth/billing/rate-limit classification and limit-drift warnings where exposed, and channel runtime resilience supports configurable managed auto-restart after repeated failing readiness scans

Scope Split

Core target areas

• Gateway runtime
• Multi-agent routing
• Sessions and session policy
• Streaming and chunking
• WhatsApp
• Telegram
• Discord
• iMessage
• Slack and channel account management
• Media support
• Voice-note transcription
• Web Control UI
• Mobile nodes
• Onboarding and pairing flows
• Memory and RAG
• Security and operator controls
• Observability for operator-significant paths

Plugin target areas

• Plugin agent tools over the shipped compiled-skill surface
• Background workflow and tool-extension model coverage
• Auth and voice-call plugin lanes over the same bounded Rust-native extension contract

Intentional divergences to preserve

• Rust-native skills/capability enforcement instead of a weaker plugin/runtime model
• First-class Rust channels such as Mattermost instead of reproducing a second plugin-channel runtime substrate
• MCP and mcp2-cli as first-class operator tooling
• Broader multi-provider model support than the minimum shipped contract requires

Out of scope for the current shipped claim

• Full source-language equivalence with another stack
• Keeping Python as a required production dependency forever
• Any undocumented internal behavior that is not exposed as user-facing supported surface

Severity Guide

• critical: major shipped capability absent from the declared surface
• high: capability exists, but would materially disappoint an operator using the declared surface
• medium: usable but incomplete
• low: the shipped surface is solid or intentionally exceeds the minimum requirement

Phase 1 Completion Note

This file, together with feature-matrix.md, product-positioning.md, and roadmap.md, is the contract for the current shipped surface.