@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/cli/commands/debug-bundle.d.ts

@@ -1,16 +1,9 @@
 /**
- * Debug bundle CLI command for kici-admin.
- *
- * Creates a sanitized diagnostic ZIP bundle by calling multiple admin API
- * endpoints and assembling the results client-side. The bundle contains
- * config, diagnostics, system info, and cluster state for troubleshooting.
- *
- * Usage: kici-admin debug-bundle [--output <path>]
+ * `kici-admin debug-bundle [--output <path>]`: a sanitized diagnostic ZIP
+ * (config, diagnostics, system info, cluster state) assembled client-side from
+ * several admin API endpoints.
  */
 import { type Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
-/**
- * Register the debug-bundle command on the CLI program.
- */
 export declare function registerDebugBundleCommand(program: Command, getClient: () => AdminApiClient): void;
 //# sourceMappingURL=debug-bundle.d.ts.map

package/dist/cli/commands/diagnose.d.ts

@@ -1,20 +1,9 @@
-/**
- * Diagnostic health check command for kici-admin.
- *
- * Calls the orchestrator's /admin/diagnose endpoint and displays
- * results as a formatted table or raw JSON.
- *
- * Exit codes:
- *   0 - all checks pass
- *   1 - any check warns
- *   2 - any check fails
- */
+/** `kici-admin diagnose`. Exit codes: 0 all pass, 1 any warns, 2 any fails. */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';
 /**
- * Width of the table's Message column. A check message is cut at this many
- * characters, so anything a check wants an operator to see in the default
- * (non-`--json`) output has to fit inside it.
+ * Messages are cut at this many characters, so what a check wants an operator
+ * to see in the default (non-`--json`) output must fit.
  */
 export declare const DIAGNOSE_TABLE_MESSAGE_WIDTH = 42;
 export declare function registerDiagnoseCommand(program: Command, getClient: () => AdminApiClient): void;

package/dist/cli/commands/event-dlq.d.ts

@@ -1,16 +1,8 @@
 /**
- * Event DLQ admin CLI commands for kici-admin.
- *
- *   event-dlq list     — list events in the DLQ
- *   event-dlq count    — total DLQ depth
- *   event-dlq retry <id>     — clear DLQ flag, schedule for retry, pg_notify
- *   event-dlq discard <id>   — permanently delete a DLQ event
- *
- * Operator triage path for at-least-once event delivery. Customers should
- * generally never see anything in the DLQ — when something lands here it
- * usually means a workflow handler is consistently failing and should be fixed
- * at its root cause. This CLI is the triage surface: inspect last_error, retry
- * once a fix is deployed, or discard if the event is no longer relevant.
+ * `kici-admin event-dlq`: operator triage for at-least-once event delivery. An
+ * event here usually means a workflow handler fails consistently: inspect
+ * last_error, retry once a fix is deployed, or discard. `retry` clears the DLQ
+ * flag, schedules a retry and sends pg_notify.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/event-log.d.ts

@@ -1,24 +1,6 @@
 /**
- * Inbound webhook delivery log commands for kici-admin.
- *
- * Operator-facing read access to the orchestrator's event_log table via the
- * admin HTTP API. Use it instead of raw psql / log-grep when an operator
- * asks "did delivery <id> arrive, and what did its payload look like".
- *
- *   event-log list   List inbound deliveries with filters
- *   event-log show   Show a single delivery (optionally with payload)
- *
- * Filter flags for `list`:
- *   --org             -> ?orgId=
- *   --routing-key     -> ?routingKey=
- *   --event           -> ?event=
- *   --action          -> ?action=
- *   --status          -> ?status=
- *   --from            -> ?from= (ISO timestamp)
- *   --to              -> ?to=   (ISO timestamp)
- *   --delivery-id     -> ?deliveryId= (substring)
- *   --limit / --offset
- *   --json            Emit raw JSON
+ * `kici-admin event-log`: read access to the inbound webhook delivery log
+ * (event_log) over the admin API — did delivery <id> arrive, and with what payload.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/execution.d.ts

@@ -1,13 +1,7 @@
 /**
- * Execution read CLI commands for kici-admin.
- *
- *   execution list [--routing-key <k>] [--status <s>] [--workflow-name <n>] [--limit <n>]
- *   execution show <runId>
- *
- * READ-ONLY — mutations (purge-stale) live in `maintenance.ts` instead.
- * Dual-mode: HTTP (via AdminApiClient) or `--database-url` (direct DB).
- *
- * The rows come from execution_runs / execution_jobs, not dedup_cache.
+ * `kici-admin execution list|show`, READ-ONLY (`purge-stale` lives in
+ * `maintenance.ts`), over HTTP or `--database-url`. Rows come from
+ * execution_runs / execution_jobs, not dedup_cache.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/firecracker/index.d.ts

@@ -1,10 +1,7 @@
 /**
- * `kici-admin firecracker` command group.
- *
- * Local host-networking ops for the orchestrator's Firecracker scaler:
- * provision/verify/teardown the per-coordinator bridge + nft table, with
- * --persist for reboot survival. These run directly on the host (privileged
- * `ip`/`nft`/`systemctl`) and do NOT use the admin HTTP client.
+ * `kici-admin firecracker`: provisions, verifies and tears down the Firecracker
+ * scaler's per-coordinator bridge and nft table (--persist survives reboots).
+ * Runs on the host with privileged `ip`/`nft`/`systemctl`, NOT the admin HTTP client.
  */
 import type { Command } from 'commander';
 export declare function registerFirecrackerCommands(program: Command): void;

package/dist/cli/commands/held-run.d.ts

@@ -1,41 +1,31 @@
 /**
- * Held-run commands for kici-admin.
+ * `kici-admin held-run <list|approve|reject>`: the local answer to a held run
+ * on an orchestrator with no Platform. Every other release surface (dashboard
+ * queue, `kici approve` / `kici reject`, developer MCP tools) is
+ * Platform-relayed, and a `/kici approve` PR comment releases only the
+ * `security` queue, so without these verbs an approval-queue hold could only
+ * expire.
  *
- * Subcommand namespace: `kici-admin held-run <list|approve|reject>`.
+ * The mirror image of `trust-policy set`: they work only where no Platform is
+ * attached, and the route refuses with 409 elsewhere. That refusal is surfaced
+ * verbatim so the CLI cannot drift from what the server said.
  *
- * The local answer to a held run, for an orchestrator that has no Platform.
- * Every other release surface is Platform-relayed — the dashboard approval
- * queue, `kici approve` / `kici reject`, and the developer MCP tools all reach
- * the applier over the control-plane connection — and the one surface that is
- * not, a `/kici approve` pull-request comment, releases the `security` queue
- * only. So on an independent orchestrator an approval-queue hold had no answer
- * at all and could only expire.
+ * By default a decision answers as the admin token, whose `service:` subject
+ * satisfies no `{user}` or `{team}` clause. `--as <user-id>` answers as a
+ * member of the approval directory (`kici-admin trust-policy directory-set`),
+ * so a clause-bearing hold has an answer. An id the directory does not carry is
+ * refused: an unvalidated subject would let a token satisfy any clause by
+ * naming it.
  *
- * These verbs are therefore the mirror image of `trust-policy set`: they work
- * only where no Platform is attached, and the route refuses with 409 wherever
- * one is. That refusal is surfaced verbatim rather than reworded here, so the
- * CLI cannot drift from what the server actually said.
- *
- * A decision answers as the admin token by default, whose `service:` subject
- * satisfies no `{user}` or `{team}` clause — enough for a hold that names
- * nobody, and nothing at all for one that does. `--as <user-id>` answers as a
- * member of the approval directory instead, the one `kici-admin trust-policy
- * directory-set` writes, so a clause-bearing hold on an independent
- * orchestrator has an answer rather than only an expiry. An id the directory
- * does not carry is refused: an unvalidated subject would let a token satisfy
- * any clause by naming it.
- *
- * A hold is named the same way `kici approve` names one — `--job` / `--step` /
- * `--hold-type` / `--hold`, resolved by the shared `resolveHeldRunId` — so an
- * operator disambiguating a doubly-held job types the same flags on either
- * surface. That sharing is the point: a job gated by BOTH a reviewer hold and a
- * security hold writes two pending rows requiring two decisions, and a second
- * resolver would be free to disagree about which one `--job` means.
+ * Holds are named with the same flags as `kici approve` (`--job` / `--step` /
+ * `--hold-type` / `--hold`) through the shared `resolveHeldRunId`: a job gated
+ * by BOTH a reviewer and a security hold has two pending rows, and a second
+ * resolver could disagree about which one `--job` means.
  */
 import type { Command } from 'commander';
 import { ApprovalDecision, type HeldRunSummary } from '@kici-dev/engine';
 import type { AdminApiClient } from '../api-client.js';
-/** One held-run row as the admin route reports it, with the clause list it adds. */
+/** The admin route adds the clause list to each row. */
 type AdminHeldRunSummary = HeldRunSummary & {
     /** Approver clauses the hold's requirement carries; `[]` when it names nobody. */
     clauses?: Array<{
@@ -44,18 +34,14 @@ type AdminHeldRunSummary = HeldRunSummary & {
         user: string;
     }>;
 };
-/** The decision response the admin route returns. */
 interface DecisionResponse {
     status: string;
     remainingClauses?: number;
 }
 /**
- * Render the pending holds for a run.
- *
- * Per-entry rather than a count: "which hold do I answer, and who may answer
- * it" is the question this command exists to answer, and the hold id it prints
- * is the `--hold <id>` disambiguator the resolver hands back when nothing else
- * separates two holds.
+ * Per-entry rather than a count: the command answers "which hold, and who may
+ * answer it", and the printed id is the `--hold <id>` disambiguator the
+ * resolver hands back when nothing else separates two holds.
  */
 export declare function formatHeldRuns(res: {
     heldRuns: AdminHeldRunSummary[];

package/dist/cli/commands/host.d.ts

@@ -1,15 +1,8 @@
 /**
- * Host roster management commands for kici-admin (orchestrator data plane).
- *
- *   host list      List all roster hosts with derived status
- *   host get       Show one roster host
- *   host declare   Pre-declare a static host before its agent connects
- *   host remove    Remove a host from the roster
- *
- * Reads/writes the orchestrator DB directly (via withDb), so this lives in
- * kici-admin — never in the public `kici` or the Platform `kici-platform-admin`.
- * Writes run as the operator: they may set reserved `kici:` labels and
- * properties, change any host, and confirm a host the dashboard created.
+ * `kici-admin host` roster commands. They use the orchestrator DB directly, so
+ * they live in kici-admin, never `kici` or `kici-platform-admin`. Writes run as
+ * the operator: they may set reserved `kici:` labels and properties, change any
+ * host, and confirm a host the dashboard created.
  */
 import type { Command } from 'commander';
 export declare function registerHostCommands(program: Command): void;

package/dist/cli/commands/inspect-bundle.d.ts

@@ -1,16 +1,8 @@
 /**
- * Inspect-bundle CLI command for kici-admin.
- *
- * Parses a previously-created debug bundle ZIP and displays a structured
- * summary with colorized output. Works fully offline -- no running
- * orchestrator or network access needed.
- *
- * Usage: kici-admin inspect-bundle <path>
+ * `kici-admin inspect-bundle <path>`: summarize a debug bundle ZIP. Fully
+ * offline: needs no running orchestrator or network.
  */
 import type { Command } from 'commander';
-/**
- * Register the inspect-bundle command on the CLI program.
- * No getClient needed -- this command works fully offline.
- */
+/** Takes no getClient: the command works offline. */
 export declare function registerInspectBundleCommand(program: Command): void;
 //# sourceMappingURL=inspect-bundle.d.ts.map

package/dist/cli/commands/local-hook.d.ts

@@ -1,16 +1,8 @@
-/**
- * Render the post-receive hook script. For each pushed ref the hook calls
- * `kici-admin source trigger-local <id> --ref <ref> --before <old> --sha <new> --base-url <url>`,
- * so a push to any branch dispatches a run for that ref, and its changed files
- * are the commits the push added (`<old>..<new>`).
- */
+/** Each pushed ref dispatches a run whose changed files are the pushed commits (`<old>..<new>`). */
 export declare function renderPostReceiveHook(opts: {
     sourceId: string;
     baseUrl: string;
 }): string;
-/**
- * Write the rendered hook into the repo's `.git/hooks/post-receive` and make it
- * executable. Throws when the path is not a git repo (no `.git/hooks` dir).
- */
+/** Write the hook as executable `.git/hooks/post-receive`; throws when there is no `.git/hooks`. */
 export declare function installPostReceiveHook(repoPath: string, script: string): string;
 //# sourceMappingURL=local-hook.d.ts.map

package/dist/cli/commands/local-trigger.d.ts

@@ -19,13 +19,13 @@ export interface LocalTriggerRequest {
 }
 /** Build the GitHub-shaped webhook request the local provider normalizer expects. */
 export declare function buildLocalTriggerRequest(input: LocalTriggerInput): LocalTriggerRequest;
-/** Read HEAD ref + sha from a local git repo (used when the operator omits --ref/--sha). */
+/** Used when the operator omits --ref/--sha. */
 export declare function readRepoHead(repoPath: string): {
     ref: string;
     sha: string;
 };
 /** The parent of `sha` in a local repo, or undefined for a root commit or an unreadable repo. */
 export declare function readParentSha(repoPath: string, sha: string): string | undefined;
-/** POST the trigger request to the orchestrator base URL. Returns the HTTP status. */
+/** Returns the HTTP status. */
 export declare function sendLocalTrigger(baseUrl: string, req: LocalTriggerRequest): Promise<number>;
 //# sourceMappingURL=local-trigger.d.ts.map

package/dist/cli/commands/orchestrator-service/drain.d.ts

@@ -1,10 +1,7 @@
 /**
- * `kici-admin orchestrator drain` / `resume` CLI verbs.
- *
- * Quiesce a coordinator before an upgrade: stop dispatching new jobs, let
- * in-flight jobs finish, report when quiesced. `--wait` polls status
- * client-side until `jobsRunning` reaches 0 or the timeout elapses; exit codes
- * are scriptable (0 quiesced/initiated, 2 wait timed out, 1 error).
+ * `kici-admin orchestrator drain` / `resume`: quiesce a coordinator before an
+ * upgrade. `--wait` polls until `jobsRunning` is 0 or the timeout elapses.
+ * Exit codes: 0 quiesced/initiated, 2 wait timed out, 1 error.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../../api-client.js';

package/dist/cli/commands/orchestrator-service/index.d.ts

@@ -1,23 +1,15 @@
 /**
- * Orchestrator service command group registration.
- *
- * Registers `kici-admin orchestrator` with install, uninstall, start, stop,
- * restart, status, logs, upgrade, drain, and resume subcommands for managing the
- * orchestrator as a system service.
- *
- * The lifecycle verbs (install/start/stop/…) manage local services directly and
- * do NOT use AdminApiClient. The drain/resume verbs DO — they talk to the running
- * coordinator's admin HTTP API to quiesce it before an upgrade.
+ * `kici-admin orchestrator`: manages the orchestrator as a system service. The
+ * lifecycle verbs act on local services and do NOT use AdminApiClient; drain
+ * and resume DO, quiescing the running coordinator before an upgrade.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../../api-client.js';
 export declare function registerOrchestratorServiceCommands(program: Command, getClient: () => AdminApiClient, 
 /**
- * Non-exiting client factory for the upgrade command. Its drain and
- * schema-guard steps improve on a path that previously did neither, so an
- * install with no admin credentials must still be able to upgrade — and
- * `getClient` exits the process rather than throwing, which a caller cannot
- * catch.
+ * Non-exiting client factory for upgrade: its drain and schema-guard steps
+ * are optional, so an install with no admin credentials still upgrades, and
+ * `getClient` exits the process, which a caller cannot catch.
  */
 tryGetClient: () => AdminApiClient | null): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/cli/commands/orchestrator-service/install-env.d.ts

@@ -1,17 +1,11 @@
 /**
- * Env-file resolution + content for `kici-admin orchestrator install`.
- *
- * Three write paths — the interactive wizard, copying a supplied --env-file,
- * or writing an enumerated stub the operator fills in by hand — plus the
- * flag/TTY precedence that picks between them. Kept out of install.ts so the
- * command action stays small and the decision + stub content are unit-testable
- * without driving the whole install through Commander.
+ * Env file for `kici-admin orchestrator install`: wizard, copied --env-file, or
+ * a stub the operator fills in. Kept out of install.ts so the mode decision and
+ * stub content are unit-testable without Commander.
  */
 import { OrchestratorMode } from '@kici-dev/engine';
 import type { OrchestratorSourceHint } from '../../wizard/orchestrator-wizard.js';
-/** Which config source the install writes the env file from. */
 export type InstallEnvMode = 'wizard' | 'env-file' | 'stub';
-/** Result of writing the install env file. */
 export interface WriteInstallEnvResult {
     /** Present only in wizard mode when the operator opted into a GitHub App source. */
     sourceHint?: OrchestratorSourceHint;
@@ -21,42 +15,31 @@ export declare const COMPOSE_QUICKSTART_URL = "https://docs.kici.dev/user/quicks
 /** Direct-ingress guide, pointed at from the stub env file's KICI_WEBHOOK_PUBLIC_URL line. */
 export declare const GITHUB_INGRESS_URL = "https://docs.kici.dev/operator/orchestrator/github-ingress/";
 /**
- * Operating mode a fresh install writes when the operator names none.
- *
- * `hybrid` is a superset of `platform`: the orchestrator accepts every
- * Platform-relayed webhook exactly as `platform` does, and additionally serves
- * its own ingress route, which verifies the HMAC signature before it acts on a
- * delivery. It requires no configuration beyond what `platform` requires, so an
- * orchestrator whose port nothing reaches behaves identically to a `platform`
- * one — while an operator who later exposes that port stops losing pushes to a
- * relay outage.
+ * Mode a fresh install writes when the operator names none. `hybrid` is
+ * `platform` plus its own HMAC-verified ingress route, with no extra
+ * configuration: with the port unreachable it behaves as `platform`, and
+ * exposing the port later stops losing pushes to a relay outage.
  */
 export declare const DEFAULT_INSTALL_MODE: OrchestratorMode;
 export interface WizardModeInput {
     /** --wizard=true / --no-wizard=false / undefined when neither is passed. */
     wizard?: boolean;
-    /** --env-file value, if any. */
     envFile?: string;
     /** --dev (spins up a local Postgres and fills the DB URL). */
     dev?: boolean;
-    /** Whether stdout is attached to an interactive terminal. */
+    /** Whether stdout is an interactive terminal. */
     isTTY: boolean;
-    /** Whether the process runs under CI (non-interactive). */
     isCI: boolean;
 }
 /**
- * Pick the install env mode. Precedence: an explicit --env-file wins; then an
- * explicit --wizard / --no-wizard; --dev keeps the stub (it provisions the DB,
- * so the wizard's DB prompt would be redundant); otherwise the wizard is the
- * default only on a bare interactive terminal (mirrors `kici init`), and every
- * non-interactive/scripted install writes the stub.
+ * Precedence: --env-file, then --wizard / --no-wizard; --dev keeps the stub (it
+ * provisions the DB, so the wizard's DB prompt is redundant); else the wizard
+ * only on an interactive non-CI terminal (as `kici init`), the stub otherwise.
  */
 export declare function resolveWizardMode(input: WizardModeInput): InstallEnvMode;
 /**
- * Build the stub env file: every required key with an inline explanation, a
- * generation command for the two secrets, and a pointer to the compose
- * quickstart. Fills KICI_DATABASE_URL from a --dev container URL when present,
- * and KICI_MODE from `--mode` when the operator named one.
+ * Every required key with an inline explanation. KICI_DATABASE_URL comes from
+ * a --dev container URL when present, KICI_MODE from `--mode`.
  */
 export declare function buildStubEnv(opts: {
     devDbUrl?: string;
@@ -65,35 +48,28 @@ export declare function buildStubEnv(opts: {
 export interface WriteInstallEnvArgs {
     mode: InstallEnvMode;
     envFilePath: string;
-    /** Source path for env-file mode. */
     envFileSource?: string;
-    /** Dev-provisioned DB URL, threaded into the stub / appended to an env file. */
+    /** Dev-provisioned DB URL, written into the stub or appended to an env file. */
     devDbUrl?: string;
     /**
-     * Operating mode from `--mode`. Written into the stub, and preselected in the
-     * wizard's mode prompt. Unset falls back to {@link DEFAULT_INSTALL_MODE}.
+     * From `--mode`: written into the stub and preselected in the wizard. Unset
+     * falls back to {@link DEFAULT_INSTALL_MODE}.
      */
     orchestratorMode?: OrchestratorMode;
     /**
-     * Whether the operator actually typed `--mode`, as opposed to Commander
-     * filling in {@link DEFAULT_INSTALL_MODE}.
-     *
-     * Only the env-file path needs the distinction. The file the operator hands
-     * in may already declare `KICI_MODE`, and the install bakes the service unit's
-     * entry point from that value — so a defaulted `hybrid` must never overwrite a
-     * joined cluster's `independent`, while a named `--mode` must.
+     * The operator typed `--mode` (Commander did not default it). The env-file
+     * path bakes the unit's entry point from its `KICI_MODE`, so a defaulted
+     * `hybrid` must never overwrite a joined cluster's `independent`, while a
+     * named `--mode` must.
      */
     modeExplicit?: boolean;
 }
 /**
- * Materialise the env file for the resolved mode.
- *
- * Every write path ends at {@link ENV_FILE_MODE}: the file carries the secrets
- * master key, so it must never be group- or world-readable. Each path that
- * creates or replaces the file stages it through a sibling temporary at that
- * mode, so the destination never exists more permissively even briefly. The
- * trailing chmod tightens the one path that only appends — a file that was
- * already there at looser permissions.
+ * Every path ends at {@link ENV_FILE_MODE}: the file holds the secrets master
+ * key, so it is never group- or world-readable. Creating or replacing stages
+ * through a sibling temporary at that mode, so the destination is never
+ * briefly looser; the trailing chmod tightens a pre-existing file the append
+ * path only extends.
  */
 export declare function writeInstallEnvFile(args: WriteInstallEnvArgs): Promise<WriteInstallEnvResult>;
 //# sourceMappingURL=install-env.d.ts.map

package/dist/cli/commands/orchestrator-service/install.d.ts

@@ -1,9 +1,6 @@
 /**
- * `kici-admin orchestrator install` command.
- *
- * Registers the orchestrator as a native system service on the current platform.
- * Auto-detects platform and privilege level, creates config directories,
- * writes env file, and registers the service with the init system.
+ * `kici-admin orchestrator install`: registers the orchestrator as a native
+ * service, auto-detecting platform and privilege level.
  */
 import type { Command } from 'commander';
 export declare function registerOrchestratorInstall(orchestrator: Command): void;

package/dist/cli/commands/orchestrator-service/status.d.ts

@@ -1,33 +1,21 @@
 /**
- * `kici-admin orchestrator status` command.
- *
- * Shows OS-level service status (state, PID, uptime) and queries the
- * running orchestrator's `/health` and `/ready` endpoints for its version,
- * build fingerprint, uptime and readiness (database reachable, boot finished).
- * With an admin token (`--token` / KICI_ADMIN_TOKEN) it also asks the
- * instance's admin API which org the Platform attached it to.
- *
- * Target resolution goes through resolveInstanceTarget — the same priority chain
- * every lifecycle command uses (--instance-dir > --name > CWD manifest >
- * refusal with candidate list).
+ * `kici-admin orchestrator status`: OS-level service state plus the running
+ * orchestrator's `/health` and `/ready`, and, with an admin token (`--token` /
+ * KICI_ADMIN_TOKEN), the Platform org from the instance's admin API. Targets
+ * resolve through resolveInstanceTarget, like every lifecycle command.
  */
 import type { Command } from 'commander';
 import { type ServicePlatform } from '../../service/index.js';
 /**
- * How long to wait for `/ready`. Its database check waits up to the pool's
- * acquire timeout before it reports `database: false`, so the wait covers that
- * timeout plus a margin. An acquire timeout of 0 lets the pool wait without
- * limit; the default then bounds the wait.
+ * `/ready`'s database check waits up to the pool acquire timeout, so the wait
+ * covers that plus a margin. An acquire timeout of 0 (unbounded) falls back to
+ * the default.
  */
 export declare function readinessTimeoutMs(envContent: string): number;
 /**
- * The config files this install owns, for an operator who wants to inspect
- * them. Derived from the instance manifest and the env file on disk, not from
- * the running service, so it answers just as well for a stopped one.
- *
- * No path is checked for existence: on bare metal such a check would pass, but
- * a compose install names host paths the check would have to run against a
- * container, blanking the answer for the shape that needs it most.
+ * The install's config files, from the manifest and env file on disk, so a
+ * stopped service answers too. No existence check: for a compose install it
+ * would have to run against the container, blanking the answer.
  */
 export declare function formatConfigPaths(args: {
     platform: ServicePlatform;

package/dist/cli/commands/orchestrator-service/upgrade.d.ts

@@ -1,20 +1,11 @@
 /**
- * `kici-admin orchestrator upgrade` command.
+ * `kici-admin orchestrator upgrade`: versioned directory layout. The new version
+ * is extracted beside the old ones (kept for rollback) and the symlink (Unix) or
+ * service registration (Windows) is switched atomically.
  *
- * Upgrades the orchestrator using the versioned directory layout:
- * - Extracts new version alongside old versions
- * - Updates symlink (Unix) or service registration (Windows) atomically
- * - Preserves old versions for rollback
- * - Supports --cleanup and --rollback flags
- *
- * Targeting is folder-anchored: the resolution priority is
- *   1. `--instance-dir <path>`
- *   2. `--name <name>`
- *   3. CWD manifest (`./.kici-orchestrator.json`)
- *   4. otherwise refuses with a candidate-list error.
- *
- * `--name` no longer has a default — every invocation must resolve via one
- * of the above paths.
+ * Targeting is folder-anchored, in priority order: `--instance-dir`, `--name`
+ * (no default), the CWD manifest (`./.kici-orchestrator.json`); otherwise it
+ * refuses with a candidate list.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../../api-client.js';

package/dist/cli/commands/org-settings.d.ts

@@ -1,16 +1,10 @@
 /**
- * Org-settings management commands for kici-admin.
+ * `kici-admin org-settings <group> <subcommand>`, against the orchestrator
+ * admin API directly (`routes/admin-org-settings.ts`), never the Platform
+ * proxy, so it works while the Platform is down.
  *
- * Subcommand namespace: `kici-admin org-settings global-workflows <subcommand>`
- * and `kici-admin org-settings dashboard-writes <subcommand>`.
- *
- * Talks to the orchestrator admin API directly (not the Platform dashboard
- * proxy), so the CLI stays operable even when Platform is unavailable. Backed
- * by `packages/orchestrator/src/routes/admin-org-settings.ts`.
- *
- * The settings row is org-scoped (one row per `customer_id`). Each pattern
- * entry can optionally pin a webhook source via `--source <routingKey>`.
- * Omitting `--source` stores the entry as "any source in the org".
+ * One settings row per `customer_id`. A pattern entry may pin a webhook source
+ * with `--source <routingKey>`; without it the entry matches any org source.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';

package/dist/cli/commands/peer.d.ts

@@ -1,7 +1,5 @@
 /**
- * Peer management commands for kici-admin.
- *
- * Provides admin operations for peer token and credential management:
+ * Peer token and credential commands for kici-admin:
  *   peer create-token   Create a join token for a new peer
  *   peer list           List active peer credentials
  *   peer revoke         Revoke a specific peer's credential
@@ -20,13 +18,10 @@ export interface PeerForgetIo {
     interactive: boolean;
 }
 /**
- * `kici-admin peer forget`: drop a departed peer from this coordinator's live
- * peer registry and every connected sibling's. Exits 1 when any coordinator
- * kept it (connected, heard from recently, or no answer).
- *
- * When the forget would switch a coordinator's event-provision backstop back
- * on, the operator confirms that consequence first; `--yes` acknowledges it up
- * front, and without a terminal the command refuses instead of asking.
+ * Exits 1 when any coordinator kept the peer (connected, heard from recently,
+ * or no answer). A forget that would switch a coordinator's event-provision
+ * backstop back on needs confirmation: `--yes` gives it up front, and without
+ * a terminal the command refuses.
  *
  * @returns the process exit code
  */

package/dist/cli/commands/queue.d.ts

@@ -1,13 +1,7 @@
 /**
- * Queue read CLI commands for kici-admin.
- *
- *   queue list [--status <s>] [--job-name-prefix <p>] [--limit <n>]
- *   queue show <id>
- *
- * READ-ONLY — mutations live in `maintenance.ts` (queue clear) instead.
- * Dual-mode: HTTP (via AdminApiClient) or `--database-url` (direct DB).
- *
- * The rows come from dispatch_queue, not a dedup cache.
+ * `queue list` / `queue show <id>`: READ-ONLY (mutations live in
+ * `maintenance.ts`, `queue clear`). Dual-mode: HTTP (AdminApiClient) or
+ * `--database-url` (direct DB). Rows come from dispatch_queue, not a dedup cache.
  */
 import type { Command } from 'commander';
 import type { AdminApiClient } from '../api-client.js';