Provide a supported daemon discovery contract for external clients

[mjacobs]

Provide a supported daemon discovery contract for external clients

While building an external read-only viewer for Kata, the first thing I needed
was to attach to the same daemon the CLI/TUI would — which meant
re-implementing the env-var precedence, .kata.local.toml walking, and local
discovery logic myself. That logic already exists in internal/client
(client.Discover, plus resolveRemote for the KATA_SERVER/local-config
precedence), but it isn't reachable from outside the module, so every external
client ends up duplicating it and drifting from the canonical behavior. This
isn't specific to a viewer; it's a prerequisite for any out-of-process client.

The OpenAPI schema work in #97 (landed in #99) gives external clients the wire
types; discovery is the other half — which daemon to send those typed
requests to. And this isn't hypothetical: #101 just changed daemon runtime
records to publish URL-shaped addresses (unix:///… / host:port) specifically
so external runtime-record consumers (the commit names Kataflow) can attach,
which is exactly the duplication this issue is about — each such consumer is
re-deriving the daemon's location from internals.

(References below are against kenn-io/kata@33cfc4b, 2026-06-05; file paths
may drift, but the discovery order and transport details are the stable part of
the ask.)

Problem

External tools need a supported way to discover the active daemon endpoint and
transport. Today this requires duplicating Kata internals (env var precedence,
config-file walking, local daemon discovery/spawn), which is fragile and drifts
from the canonical behavior.

Proposal

Document and expose the daemon discovery contract so external clients can locate
and attach to the right daemon the same way the Kata CLI/TUI does. This is the
umbrella "how do I find and connect to the daemon" contract. A natural extension
(possibly a follow-up issue) is letting a client confirm it reached the
expected daemon/database — e.g. surfacing the database's instance_uid (the
daemon already stores this in the meta table and exposes it via
/api/v1/instance) on a status/health response — but that only adds value if it
returns fields discovery itself does not.

A documented discovery contract lets any external client connect reliably
without reverse-engineering internal behavior, and keeps clients correct across
Kata upgrades.

• Document the discovery order: KATA_SERVER, .kata.local.toml
  ([server] url, walking up from the workspace/cwd), then local daemon.
• Expose discovery logic through a supported surface (the exact shape is
  yours to decide) — for example, a public Go entry point for the existing
  internal/client.Discover logic to support Go integrations, and/or a
  machine-readable CLI command (something like kata daemon locate --json)
  to support non-Go integrations.
• Include Unix-socket vs HTTP transport details — i.e. document the
  address form clients should expect (the Endpoint().ConfigAddress()
  shape that fix(daemon): publish unix runtime addresses as URLs #101 standardized: unix:///… for local sockets, host:port
  for TCP), so consumers don't each re-derive it.
• Avoid exposing secrets (e.g. bearer tokens) in ordinary output.