diff --git a/client/continuation.go b/client/continuation.go
index f919676..41d4d90 100644
--- a/client/continuation.go
+++ b/client/continuation.go
@@ -98,6 +98,20 @@ func ChatWithContinuation(ctx context.Context, p Provider, messages []EyrieMessa
 // the response stops with "max_tokens" and contains only text (no tool calls).
 // It returns a StreamResult whose Events channel transparently continues across
 // multiple LLM calls, emitting a "continuation" event at each boundary.
+//
+// DEPRECATION NOTE: hawk's Session loop has its own max_tokens recovery
+// (internal/engine/stream.go around the `recoveryCount` loop) that doesn't
+// add a synthetic "Continue." user message, and the eyrie conversation
+// engine (eyrie/conversation.Engine) has its own OutputGroupID-based
+// engine-level continuation. The two engine-level paths produce cleaner
+// conversation shapes (no synthetic user turns) and are the recommended
+// pattern for new code. This client-level helper remains for
+// backwards-compatibility with the embedded eyrie HTTP server and
+// non-hawk consumers; new code should implement continuation at the
+// engine or call-site level instead.
+//
+// Will be removed in eyrie v0.3.0. See eyrie/CHANGELOG.md for the
+// deprecation timeline.
 func StreamChatWithContinuation(ctx context.Context, p Provider, messages []EyrieMessage, opts ChatOptions, cfg ContinuationConfig) (*StreamResult, error) {
 	if cfg.MaxContinuations <= 0 {
 		cfg.MaxContinuations = 3
diff --git a/runtime/runtime.go b/runtime/runtime.go
index e71506c..1557d16 100644
--- a/runtime/runtime.go
+++ b/runtime/runtime.go
@@ -1,5 +1,25 @@
-// Package runtime is the only stable API surface for host applications (e.g. hawk).
-// Import github.com/GrayCodeAI/eyrie/runtime — not catalog/setup/config directly.
+// Package runtime is the **recommended entry point** for host applications
+// (e.g. hawk). Start by calling runtime.Load to get a *Runtime, then
+// rt.ChatProvider to obtain a client.Provider that you can hand to your
+// agent loop.
+//
+// Note: the "stable" surface of eyrie is actually a set of cooperating
+// subpackages, not just this one. The full list hawk (and other host
+// applications) actually import is:
+//
+//	github.com/GrayCodeAI/eyrie/runtime          (this package — bootstrap facade)
+//	github.com/GrayCodeAI/eyrie/client           (Provider interface, message/response types)
+//	github.com/GrayCodeAI/eyrie/catalog         (model catalog: pricing, capabilities, registry)
+//	github.com/GrayCodeAI/eyrie/catalog/registry (ProviderSpec catalog: 16 registered providers)
+//	github.com/GrayCodeAI/eyrie/catalog/xiaomi  (Xiaomi-specific catalog helpers)
+//	github.com/GrayCodeAI/eyrie/config          (provider config + env var resolution)
+//	github.com/GrayCodeAI/eyrie/credentials     (OS keyring + OIDC keyless CI auth)
+//	github.com/GrayCodeAI/eyrie/setup           (CLI/setup wiring, RoutingPreviewJSON)
+//	github.com/GrayCodeAI/eyrie/storage         (conversation DAG persistence)
+//
+// They are all considered part of the public API; changes to exported
+// names are gated by semver. Anything under internal/ is implementation
+// detail and may change without notice.
 package runtime
 
 import (