@interactive-inc/claude-funnel 0.53.0 → 0.56.0

package/dist/funnel-docs-ng5K8w4j.js

@@ -0,0 +1,653 @@
+//#endregion
+//#region lib/services/docs/funnel-docs.ts
+const DOCS = {
+	architecture: `funnel docs architecture — how Funnel routes events
+
+Funnel is a hub between external sources (Slack / GitHub / Discord / cron) and
+Claude Code agents. Events flow one way; replies flow back via MCP tools.
+
+  external sources → daemon → channel → agent (MCP)
+                         ↑ ← outbound replies (MCP tools)
+
+layers (dependency direction):
+
+  engine ← connectors ← gateway ← cli
+                                ↖ bin.ts → funnel.ts (facade)
+
+  engine      core domain (channels, profiles, settings, mcp, local-config)
+  connectors  slack / gh / discord / schedule implementations
+  gateway     Bun.serve hosting WS + internal HTTP, listener supervisor,
+              broadcaster, event log (SQLite by default)
+  cli         argv → internal HTTP requests → Hono routes
+
+runtime processes:
+
+  daemon         long-lived gateway in its own process; spawned by fnl claude;
+                 shared across Claude sessions and repos
+  in-process     same gateway hosted inside the embedding process; for tests
+                 and custom hosts; observe events with onEvent()
+
+storage roots:
+
+  ~/.funnel/                       global daemon state (PID, token, settings)
+  ~/.funnel/projects/<id>/         per-repo state when funnel.json exists
+  /tmp/funnel/                     event store + connector diagnostic SQLite
+
+key invariants:
+
+  - listener and adapter are separate one-way pipes (broadcaster sees only
+    inbound events, not outbound tool calls)
+  - per-repo state is fully isolated from global state — they never mix
+  - URL building is type-safe via channelWsUrl / gatewayLoopbackUrl helpers
+
+related: fnl docs channels, fnl docs profiles, fnl docs mcp`,
+	channels: `funnel docs channels — what a channel is
+
+A channel is a subscription mailbox. It owns connectors and decides how events
+fan out to subscribers.
+
+shape:
+
+  { id, name, delivery, connectors[] }
+
+delivery modes:
+
+  fanout      every subscriber receives every event. Use when each subscriber
+              has its own job (multiple profiles processing the same source,
+              observer clients tapping in).
+  exclusive   one event goes to one subscriber, round-robin. Use when
+              subscribers are interchangeable workers and each event must be
+              processed exactly once.
+
+what a channel does NOT own:
+  - launch options (those live on Profile)
+  - sessions (those live on Profile)
+  - tokens (those live in per-repo settings)
+
+operations:
+
+  fnl channels                            list channels
+  fnl channels <name>                     show one channel
+  fnl channels add <name>                 create a channel
+  fnl channels remove <name>              delete a channel
+  fnl channels rename <old> <new>         rename a channel
+  fnl channels <name> set delivery <mode> change delivery to fanout|exclusive
+  fnl channels <name> publish             publish a synthetic event
+  fnl channels <name> validate            sanity-check a channel
+
+connectors live nested inside a channel — see fnl docs connectors.
+
+related: fnl docs connectors, fnl docs profiles`,
+	claude: `funnel docs claude — launching Claude Code through funnel
+
+\`fnl claude\` spawns Claude with the channel subscription wired in. The
+resolution order is:
+
+  1. --help / -h                            print help
+  2. --profile + --channel                  error (mutually exclusive)
+  3. --profile <name>                       use named profile (global first,
+                                            then cwd funnel.json profiles[])
+  4. funnel.json exists + --channel <name>  bind transport, no recipe
+  5. funnel.json exists, no --channel       bind first channel in channels[]
+  6. no funnel.json + --channel <name>      raw launch
+  7. default global profile                 launch
+  8. nothing matches                        print help
+
+argv assembly when spawning Claude:
+
+  [profile.options] [user CLI args] [MCP server flag]
+
+  Same flag specified twice → last one wins.
+  env assembled as: profile.env merged with process.env (process.env wins).
+
+side effects on first launch in a repo:
+
+  - writes funnel.json's top-level "id" (uuid) if missing — used to isolate
+    state under ~/.funnel/projects/<id>/
+  - installs an entry into the repo's .mcp.json (does not touch other entries)
+  - if a connector has no token, TTY-prompts and saves to per-repo settings
+
+double-launch guard:
+
+  Same profile cannot be launched twice — protected by a PID file under
+  ~/.funnel/projects/<id>/profiles/<profile-id>/pid. Stale PID files are
+  cleaned up automatically when the recorded process is gone.
+
+related: fnl docs profiles, fnl docs mcp, fnl docs local-config`,
+	connectors: `funnel docs connectors — external service bindings
+
+A connector is one connection to one external service. It is nested inside a
+channel — a channel can host several connectors of different types.
+
+types:
+
+  slack      Socket Mode listener + REST adapter
+  gh         GitHub polling listener + REST adapter
+  discord    Discord listener + REST adapter
+  schedule   cron-style tick listener (no adapter — schedule does not send out)
+
+per-type parts:
+
+  Listener   external → Funnel inbound. push (Slack), pull (GitHub), or tick
+             (Schedule cron).
+  Adapter    Claude → external outbound. only on callable types.
+  Schema     config validation.
+  EventProcessor  shapes raw events into the channel payload.
+
+operations (all nested under a channel):
+
+  fnl channels <ch> connectors                       list
+  fnl channels <ch> connectors <name>                show
+  fnl channels <ch> connectors add <name> --type=…   create
+  fnl channels <ch> connectors set <name> …          update
+  fnl channels <ch> connectors remove <name>         delete
+  fnl channels <ch> connectors rename <old> <new>    rename
+  fnl channels <ch> connectors <name> request …      proxy an HTTP call to the
+                                                     adapter (e.g. send a Slack
+                                                     message via Claude path)
+  fnl channels <ch> connectors <name> schedules …    manage cron entries on a
+                                                     schedule connector
+
+tokens:
+
+  funnel.json must NOT contain tokens. Set them via:
+
+    fnl channels <ch> connectors set <name> --bot-token-env=SLACK_BOT_TOKEN
+
+  …or leave unset and fnl claude will TTY-prompt at first launch and persist
+  to ~/.funnel/projects/<id>/settings.json.
+
+related: fnl docs channels, fnl docs debugging`,
+	debugging: `funnel docs debugging — diagnose and self-heal in one shot
+
+Funnel ships with a single entry point that diagnoses every channel and, when
+asked, applies safe self-healing fixes. Use this from the CLI (fnl doctor),
+the MCP server (fnl_doctor tool), or the SDK (funnel.doctor.run()).
+
+── the one command Claude needs ─────────────────────────────────────────────
+
+  fnl doctor                          read-only diagnosis
+  fnl doctor --fix --json             diagnose + apply safe fixes (idempotent)
+  fnl doctor --fix --aggressive       also restart the gateway if needed
+
+Return shape (same for CLI --json, MCP, SDK):
+
+  { status: "ok" | "warn" | "error",
+    message: "...",
+    appliedActions: [
+      { kind: "gateway:started" }
+    | { kind: "gateway:already-running" }
+    | { kind: "gateway:restarted" }
+    | { kind: "listener:restarted",  channel, connector }
+    | { kind: "listener:skipped",    channel, connector, reason }
+    ],
+    remainingIssues: [
+      { channel, diagnosis: { status, message, nextActions, rootCause } }
+    ],
+    before: <diagnoseAll snapshot before fixing>,
+    after:  <diagnoseAll snapshot after fixing> }
+
+When status is "ok" you are done. Otherwise read remainingIssues for what
+is still broken — usually a hint Claude can act on (configure a missing
+connector, prompt the user to run \`fnl gateway start\` in a shell, etc).
+
+── what fnl doctor --fix will and will not do ──────────────────────────────
+
+Will (safe):
+  - start the gateway if it is down (when run as a CLI; MCP cannot do this)
+  - restart every dead listener across every channel
+
+Will (aggressive, only with --aggressive):
+  - also restart the gateway when safe fixes are not enough
+
+Will not:
+  - create channels / connectors / profiles
+  - rotate tokens
+  - change persistent config
+
+── deeper inspection (rarely needed) ───────────────────────────────────────
+
+  fnl debug events  --channel <name>     processed events with outcome
+                                         (emitted | skip:type | skip:dedup | …)
+  fnl debug dropped --channel <name>     skip:* events only
+  fnl debug errors  --channel <name>     listener auth-failed / error events
+  fnl debug replay  --channel <name>     replay a past event to test a fix
+
+  fnl gateway logs                       daemon log stream
+  fnl gateway sql --preset recent        ad-hoc SQL queries
+
+── from inside MCP ─────────────────────────────────────────────────────────
+
+Claude in any repo calls these tools without leaving MCP:
+
+  fnl_doctor                       == fnl doctor (mode: off | safe | aggressive)
+  fnl_status                       == lightweight snapshot
+  fnl_debug                        == per-channel diagnosis
+  fnl_recent_events                == fnl debug events
+  fnl_dropped_events               == fnl debug dropped
+  fnl_connection_errors            == fnl debug errors
+  fnl_replay_event                 == fnl debug replay
+  fnl_docs                         == fnl docs
+
+── programmable API ───────────────────────────────────────────────────────
+
+  const funnel = new Funnel()
+  await funnel.doctor.run()             // read-only diagnosis
+  await funnel.doctor.run("safe")       // diagnose + safe fixes
+  await funnel.doctor.run("aggressive") // diagnose + safe + gateway restart
+
+  // Building blocks (rarely needed; doctor orchestrates them)
+  await funnel.diagnostics.diagnoseAll()
+  await funnel.recovery.ensureGatewayRunning()
+  await funnel.recovery.restartAllDeadListeners()
+
+CLI, MCP, and the SDK share exactly one implementation — the CLI is a thin
+presentation layer over funnel.doctor.
+
+related: fnl docs gateway, fnl docs mcp, fnl docs recipes`,
+	gateway: `funnel docs gateway — the WebSocket + HTTP daemon
+
+The gateway is a long-lived Bun.serve process that hosts every realtime
+boundary in funnel. Without it: store edits work, but no events flow and
+Claude cannot send anything outbound.
+
+what runs inside:
+
+  WebSocket /                   channel subscriptions (subprotocol auth)
+  HTTP /health /status          liveness and supervisor snapshot
+  HTTP /listeners*              listener lifecycle
+  HTTP /channels/<n>/call       outbound dispatch (Claude → adapter → external)
+  Listener Supervisor           starts / stops / restarts listeners with
+                                exponential backoff (cap 60s)
+  Broadcaster                   fans events out to WS clients and records
+                                offsets to the event log
+  FunnelEventLog                persistent replay log; default is
+                                SqliteFunnelEventLog under /tmp/funnel/
+
+ports:
+
+  9742    in-process / embedded (Funnel.gatewayServer())
+  9743    CLI launches (fnl claude / fnl gateway start)
+  FUNNEL_PORT overrides both
+
+bind:
+
+  127.0.0.1 (loopback) by default — unreachable off-box.
+  FUNNEL_HOST=0.0.0.0 exposes the gateway; in that mode every privileged
+  endpoint requires a bearer token, and an unprotected start() throws.
+
+operations:
+
+  fnl gateway                     overview
+  fnl gateway status              running? pid? port? uptime?
+  fnl gateway start               spawn daemon and wait until /health responds
+  fnl gateway stop                stop daemon
+  fnl gateway restart             stop + start
+  fnl gateway run                 run gateway in the foreground (no daemonize)
+  fnl gateway listeners           list listeners with alive / event / error
+                                  counts
+  fnl gateway logs                stream raw daemon logs
+  fnl gateway sql --preset recent query the diagnostic SQLite stores
+
+when do you need the gateway?
+
+  needs gateway:    fnl claude, MCP inbound, MCP outbound (channel call),
+                    fnl debug (reads /status + /tmp/funnel/*.db)
+  no gateway:       fnl channels add / remove, fnl profiles add, fnl schema
+
+related: fnl docs debugging, fnl docs architecture`,
+	glossary: `funnel docs glossary — vocabulary reference
+
+Channel
+  Subscription mailbox. Holds connectors and decides fan-out behavior.
+  See: fnl docs channels.
+
+Connector
+  One binding to one external service (slack | gh | discord | schedule),
+  nested inside a channel. Has a Listener and (when callable) an Adapter.
+  See: fnl docs connectors.
+
+Profile
+  Saved launch preset for Claude. Binds a channel and carries argv / env /
+  resume / sessionId. Not required to launch.
+  See: fnl docs profiles.
+
+LocalConfig
+  The funnel.json file at a repo root. Declares channels + profiles for that
+  repo and gets an "id" uuid stamped on first launch.
+  See: fnl docs local-config.
+
+Gateway
+  Long-lived Bun.serve daemon hosting WebSocket + internal HTTP + listener
+  supervisor + broadcaster. Required for any realtime flow.
+  See: fnl docs gateway.
+
+Listener
+  External → Funnel inbound side of a connector. Push (Slack), pull (GitHub),
+  or tick (Schedule). Supervised, auto-restarted with backoff.
+
+Adapter
+  Claude → external outbound side of a connector. Reached via MCP tool calls
+  that hit the gateway over HTTP and dispatch through the adapter.
+
+Broadcaster
+  In-gateway component that takes notifies, records them to the event log,
+  fans them out to WS subscribers.
+
+FunnelEventLog
+  Persistent replay log (default: SQLite). Enables resubscribers to catch up
+  from a saved offset via ?since=<N>.
+
+Subscriber ID
+  A WS client identifier. Events with meta.target=<id> route to that
+  subscriber only — used for per-Claude targeting.
+
+Delivery mode
+  fanout (every subscriber gets every event) or exclusive (round-robin one-
+  event-one-subscriber). Set on the channel.
+
+MCP
+  Model Context Protocol. Funnel hosts an MCP server (fnl mcp) that Claude
+  Code launches; events flow in as notifications, outbound calls flow out as
+  tool invocations.
+  See: fnl docs mcp.
+
+related: fnl docs architecture`,
+	"local-config": `funnel docs local-config — the per-repo funnel.json
+
+funnel.json lives at the repo root and is committed alongside the code. It
+declares channels (transport) and profiles (launch recipes) so a clone of the
+repo can launch Claude with the same wiring.
+
+shape:
+
+  LocalConfig = { id?, channels: ChannelSpec[], profiles?: ProfileSpec[] }
+  ChannelSpec = { name, connectors? }
+  ProfileSpec = { name, channel, options?, env?, resume? }
+
+what funnel writes back to funnel.json:
+
+  Only the top-level "id" (uuid), written once on first launch. It is the
+  state-isolation key — every funnel state for this repo lives under
+  ~/.funnel/projects/<id>/. Renaming the repo or moving it does not break
+  this binding.
+
+what funnel never writes to funnel.json:
+
+  tokens. funnel.json is commit-safe. Tokens live in:
+
+    ~/.funnel/projects/<id>/settings.json   per-repo, set via CLI or TTY prompt
+
+how it is read:
+
+  All CLI commands check for funnel.json in cwd. If found, FUNNEL_DIR is
+  pointed at the per-repo root before anything else loads, so routing,
+  dispatchClaude, MCP, and the daemon all share the same state.
+
+generating the schema for editors:
+
+  fnl schema > funnel.schema.json
+
+  # then in funnel.json:
+  { "$schema": "./funnel.schema.json", ... }
+
+related: fnl docs profiles, fnl docs channels, fnl schema`,
+	mcp: `funnel docs mcp — the MCP server inside funnel
+
+\`fnl mcp\` is invoked by Claude Code via .mcp.json (auto-installed when fnl
+claude runs in a repo). It hosts two independent pipes over one stdio MCP
+server.
+
+inbound (events → Claude):
+
+  - WebSocket subscribes to the gateway on the channel set by FUNNEL_CHANNEL_ID
+  - forwards messages as MCP notifications under method
+    "notifications/claude/channel"
+  - capability "experimental: { claude/channel: {} }" must be enabled
+  - auto-reconnects with exponential backoff and replays missed events using
+    ?since=<offset> against the gateway's persistent event log
+
+outbound (Claude → external):
+
+  - reads the channel's connectors at startup
+  - exposes one MCP tool per connector (one tool = one connector name)
+  - tool args: { method, path, body? }
+  - tool calls become HTTP POST to the gateway's channel call endpoint with
+    Bearer auth; the JSON response is returned to Claude verbatim (no bash hop)
+  - schedule connectors are excluded (no outbound side)
+
+built-in diagnostic tool:
+
+  - funnel_diagnose
+    returns the same structured report as \`fnl debug --all --json\`.
+    Call this when events stop arriving, when a tool call fails, or before
+    asking the user to check anything. No arguments required.
+
+env contract:
+
+  FUNNEL_CHANNEL_ID   set by launcher; without it the inbound side is no-op
+  FUNNEL_DIR          state root; set by the launcher for repo-scoped runs
+  FUNNEL_PORT         gateway port; default 9743 for CLI launch, 9742 for
+                      embedded use
+
+operations:
+
+  fnl mcp                  run as MCP server (do not invoke manually — Claude
+                           launches it via .mcp.json)
+
+related: fnl docs claude, fnl docs debugging`,
+	profiles: `funnel docs profiles — launch presets for Claude
+
+A profile is a saved recipe for launching Claude bound to a specific channel.
+Profiles are NOT required — \`fnl claude --channel <name>\` works without one.
+Use profiles when you want to save options / env / resume settings.
+
+shape:
+
+  { id, name, path, channelId, options[], env, resume, sessionId? }
+
+  id          uuid primary key; survives rename (used as the key for PID file
+              and sessionId so renaming a profile does not orphan its state)
+  name        display label; what --profile <name> matches
+  path        cwd to enter before spawning Claude
+  channelId   the channel this profile binds
+  options     argv prepended to claude (e.g. --agent, --brief, --model)
+  env         env vars for Claude; process.env wins on collision
+  resume      whether to reuse the saved sessionId on next launch
+  sessionId   execution state — last spawned Claude session id (not config)
+
+global vs local:
+
+  global profiles  ~/.funnel/settings.json  →  --profile <name> always works
+  local profiles   funnel.json profiles[]   →  per-repo recipe, only resolved
+                                               when cwd contains the file
+
+mutual exclusion:
+
+  --profile and --channel are mutually exclusive. A profile already binds a
+  channel, so combining them is an error.
+
+operations:
+
+  fnl profiles                              list
+  fnl profiles add <name>                   create
+  fnl profiles set <name>                   update
+  fnl profiles remove <name>                delete
+  fnl profiles rename <old> <new>           rename (id-stable)
+  fnl profiles <name> as-default            mark as default for fnl claude
+  fnl profiles <name> run                   spawn Claude using this profile
+  fnl claude --profile <name>               equivalent to <name> run
+
+related: fnl docs claude, fnl docs channels`,
+	"programmable-api": `funnel docs programmable-api — Funnel as an SDK
+
+Everything funnel does as a CLI is also a programmable API. Build your own CLI,
+TUI, web UI, or service on top of the same engine — the CLI itself is a thin
+Hono app over these services.
+
+── installation ────────────────────────────────────────────────────────────
+
+  npm install @interactive-inc/claude-funnel
+
+── facade ──────────────────────────────────────────────────────────────────
+
+  import { Funnel } from "@interactive-inc/claude-funnel"
+
+  const funnel = new Funnel()             // uses ~/.funnel
+  const sandbox = Funnel.inMemory()        // touches no disk / process / clock
+
+  funnel.paths                            // { dir, tmpDir, settings }
+  funnel.channels                         // CRUD on channels + nested connectors
+  funnel.profiles                         // CRUD on launch presets
+  funnel.localConfig                      // funnel.json read / write
+  funnel.localConfigSync                  // funnel.json → ~/.funnel sync
+  funnel.gateway                          // daemon lifecycle (start/stop/status)
+  funnel.gatewayToken                     // bearer token mint/read
+  funnel.publisher                        // POST /channels/:name/publish
+  funnel.listeners                        // listener registry control
+  funnel.claude                           // FunnelClaude (launch Claude Code)
+  funnel.diagnostics                      // read-side diagnosis (no mutation)
+  funnel.recovery                         // self-healing actions
+  funnel.docs                             // embedded documentation
+
+── independent service classes (compose freely) ────────────────────────────
+
+Each service depends on narrow interfaces, so you can wire them outside the
+facade if you want a lighter-weight integration. The Funnel facade is the
+recommended path — but it is just one composition root, not the only one.
+
+  import {
+    FunnelChannels,
+    FunnelDiagnostics,
+    FunnelRecovery,
+    FunnelDocs,
+    FunnelGatewayServer,
+    MemoryFunnelFileSystem,
+    MemoryFunnelProcessRunner,
+    MemoryFunnelClock,
+  } from "@interactive-inc/claude-funnel"
+
+── sub-entry imports ───────────────────────────────────────────────────────
+
+For targeted imports (smaller bundle / clearer dependency footprint):
+
+  import { FunnelGatewayServer } from "@interactive-inc/claude-funnel/gateway"
+  import { FunnelProfiles }      from "@interactive-inc/claude-funnel/profiles"
+  import { FunnelLocalConfig }   from "@interactive-inc/claude-funnel/local-config"
+
+── building your own CLI ───────────────────────────────────────────────────
+
+The Funnel CLI is a Hono app you can embed:
+
+  import { cliRoutes, toRequest } from "@interactive-inc/claude-funnel"
+  import { Funnel } from "@interactive-inc/claude-funnel"
+
+  const funnel = new Funnel()
+  const { method, url } = toRequest(process.argv.slice(2))
+  const res = await cliRoutes.request(url, { method }, { funnel })
+
+Or skip the routing layer entirely and call the services directly:
+
+  await funnel.diagnostics.diagnoseAll()
+  await funnel.recovery.restartAllDeadListeners()
+
+── testing ─────────────────────────────────────────────────────────────────
+
+Every IO boundary has a Memory implementation. Wire a sandboxed Funnel for
+fast, hermetic tests:
+
+  import { Funnel } from "@interactive-inc/claude-funnel"
+  const funnel = Funnel.inMemory()
+
+  funnel.channels.add({ name: "ops" })
+  expect(funnel.channels.list()).toHaveLength(1)
+
+related: fnl docs architecture, fnl docs debugging, fnl docs mcp`,
+	recipes: `funnel docs recipes — common task playbooks
+
+— bootstrap a new repo —
+
+  cd my-repo
+  fnl channels add ops
+  fnl channels ops connectors add slack-main --type=slack --bot-token-env=SLACK_BOT_TOKEN
+  fnl claude                         # auto-installs .mcp.json, launches Claude
+
+— add a second Slack workspace to one channel —
+
+  fnl channels ops connectors add slack-eu --type=slack --bot-token-env=SLACK_EU_TOKEN
+
+  Both connectors push events into the same channel; subscribers see all.
+
+— two profiles sharing one channel —
+
+  fnl channels add support
+  fnl profiles add triage   --channel=support --options=--agent,triage
+  fnl profiles add resolve  --channel=support --options=--agent,resolver
+  fnl claude --profile triage    # in one terminal
+  fnl claude --profile resolve   # in another
+
+  Pick channel delivery=exclusive so each event goes to exactly one of them.
+
+— schedule a daily cron prompt —
+
+  fnl channels add daily
+  fnl channels daily connectors add cron --type=schedule
+  fnl channels daily connectors cron schedules add morning \\
+    --cron="0 9 * * *" --prompt="summarize yesterday's PRs"
+
+— diagnose "events stopped arriving" —
+
+  fnl debug --all --json
+  # read diagnosis.rootCause and diagnosis.nextActions[] from the result
+
+— replay a real event to test a code change —
+
+  fnl debug events --channel ops --limit 5
+  fnl debug replay --channel ops --seq <pick from above>
+
+— recover from a stuck gateway —
+
+  fnl gateway logs               # confirm symptoms first
+  fnl gateway restart
+  fnl debug --all --json         # verify everything came back up
+
+related: fnl docs debugging, fnl docs channels, fnl docs profiles`
+};
+const SUMMARIES = {
+	architecture: "how Funnel routes events end-to-end",
+	channels: "what a channel is and how delivery modes work",
+	connectors: "external service bindings nested in channels",
+	profiles: "named Claude launch presets",
+	claude: "fnl claude resolution order and argv assembly",
+	mcp: "the MCP server, inbound notifications, outbound tools",
+	gateway: "the WebSocket + HTTP daemon",
+	"local-config": "the per-repo funnel.json file",
+	debugging: "ladder for diagnosing event delivery problems",
+	"programmable-api": "Funnel as an SDK; build your own CLI/UI on the engine",
+	recipes: "common task playbooks",
+	glossary: "vocabulary reference"
+};
+/**
+* Programmable docs surface — used by both the CLI (fnl docs <topic>) and the
+* MCP / SDK consumers. Docs are embedded into the build so a Claude session
+* can self-discover funnel's vocabulary without external network access.
+*/
+var FunnelDocs = class {
+	constructor() {
+		Object.freeze(this);
+	}
+	list() {
+		return Object.keys(DOCS).sort().map((name) => ({
+			name,
+			summary: SUMMARIES[name] ?? ""
+		}));
+	}
+	get(topic) {
+		return DOCS[topic] ?? null;
+	}
+	topics() {
+		return Object.keys(DOCS).sort();
+	}
+};
+//#endregion
+export { FunnelDocs as t };

package/dist/funnel-doctor-BF3Rdgk0.d.ts

@@ -0,0 +1,34 @@
+import { c as FunnelDiagnostics, n as DiagnoseAllReport, t as ChannelDiagnosis } from "./funnel-diagnostics-qWy5tPSq.js";
+import { n as RecoveryAction, t as FunnelRecovery } from "./funnel-recovery-BUBsu7WX.js";
+
+//#region lib/services/doctor/funnel-doctor.d.ts
+type Props = {
+  diagnostics: FunnelDiagnostics;
+  recovery: FunnelRecovery;
+};
+type DoctorFixMode = /** No mutations. Run diagnoseAll and report what would be fixed. */"off" /** Apply only idempotent, low-risk fixes — start the gateway, restart dead listeners. */ | "safe" /** Add high-impact fixes — full gateway restart when partial fixes are insufficient. */ | "aggressive";
+type DoctorReport = {
+  /** "ok" if every channel is healthy after the run; "warn" if anything is still off; "error" if a fix step itself failed. */status: "ok" | "warn" | "error"; /** Human-readable summary suitable for stdout. */
+  message: string; /** Aggregated diagnosis after any fix pass. */
+  after: DiagnoseAllReport; /** Diagnosis before fixing, only included when fix mode is not "off". */
+  before: DiagnoseAllReport | null; /** Each recovery action that ran during the fix pass. */
+  appliedActions: RecoveryAction[]; /** Channels still unhealthy after the fix pass (or all unhealthy channels when fix is off). */
+  remainingIssues: Array<{
+    channel: string;
+    diagnosis: ChannelDiagnosis["diagnosis"];
+  }>;
+};
+/**
+ * One-shot diagnose-and-fix entry point. The CLI exposes this as `fnl doctor`,
+ * the MCP server exposes it as `fnl_doctor`. Both surfaces should prefer this
+ * over chaining FunnelDiagnostics and FunnelRecovery by hand — the orchestration
+ * logic (which fixes to attempt, in what order, when to escalate) lives here.
+ */
+declare class FunnelDoctor {
+  private readonly props;
+  constructor(props: Props);
+  run(mode?: DoctorFixMode): Promise<DoctorReport>;
+  private buildReport;
+}
+//#endregion
+export { DoctorReport as n, FunnelDoctor as r, DoctorFixMode as t };