docs: clarify stable subpackages + deprecate client-level continuation (#31)

Two related eyrie doc improvements:

1. **runtime package doc** — the previous text said 'Import eyrie/runtime —
   not catalog/setup/config directly', but hawk (and other consumers) actually
   import a wider set of subpackages. The stable surface is cooperating
   subpackages, not just runtime. List them explicitly so contributors
   don't get confused.

   hawk imports 8 distinct subpackages of eyrie:
     - runtime          (bootstrap facade: Load, ChatProvider, etc.)
     - client           (Provider interface, message/response types)
     - catalog          (model catalog: pricing, capabilities)
     - catalog/registry (ProviderSpec catalog: 16 registered providers)
     - catalog/xiaomi   (Xiaomi-specific catalog helpers)
     - config           (provider config + env var resolution)
     - credentials      (OS keyring + OIDC keyless CI auth)
     - setup            (CLI/setup wiring, RoutingPreviewJSON)
     - storage          (conversation DAG persistence, embedded server)

   All are part of the public API; changes are gated by semver. Anything
   under internal/ is implementation detail and may change without notice.

2. **deprecate StreamChatWithContinuation** — there are now three continuation
   mechanisms in the eyrie/hawk ecosystem and the client-level one is the
   least attractive:

     a. Engine-level (eyrie/conversation) — uses OutputGroupID to collapse
        continuation chunks; no synthetic 'Continue.' user turn. Cleanest
        conversation shape.
     b. Hawk Session loop (hawk/internal/engine/stream.go) — its own
        max_tokens recovery (the recoveryCount loop) that only kicks in
        for no-tool-call continuations. Also clean.
     c. Client-level (this function) — appends 'Continue.' user turn and
        emits 'continuation' event markers. Works but pollutes the
        conversation with synthetic user messages.

   Mark (c) deprecated in favor of (a) and (b). Behaviour unchanged;
   will be removed in eyrie v0.3.0.

Author: Patel230

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

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 (