@edspencer/paddock 0.0.1 → 0.57.0

package/packages/server/dist/config.d.ts

@@ -0,0 +1,538 @@
+import { type DriveMode } from "./models.js";
+import { type RecoveryConfig } from "./recovery-config.js";
+import { type CurationConfig } from "./curation-config.js";
+import { type ManagementApiConfig, type ManagementApiConfigFile } from "./management-config.js";
+import { type AttachmentsConfig } from "./attachments-config.js";
+/**
+ * User-authentication strategy.
+ *
+ * - `none`            — no auth; every request is anonymous (default, fully open).
+ * - `trusted-header`  — trust a reverse proxy to have authenticated the user and
+ *                       pass identity in headers. Spoofable unless the proxy is
+ *                       the only path to paddock (network-level trust).
+ * - `jwt`             — verify a signed JWT (issued by the proxy/IdP) against a
+ *                       remote JWKS. Self-contained / zero-trust: spoof-proof
+ *                       even if a request reaches paddock directly.
+ */
+export type AuthMode = "none" | "trusted-header" | "jwt";
+/**
+ * Resolved authentication configuration (provider-agnostic).
+ *
+ * Driven entirely by `PADDOCK_AUTH_*` env vars so paddock is not coupled to any
+ * single proxy/IdP (Authentik, oauth2-proxy, Authelia, Cloudflare Access,
+ * Keycloak, …). See AUTH.md for the modes and provider examples.
+ */
+export interface AuthConfig {
+    mode: AuthMode;
+    /** trusted-header: header carrying the username (required in that mode). */
+    userHeader: string;
+    /** trusted-header: optional header carrying the user's email. */
+    emailHeader?: string;
+    /**
+     * trusted-header / jwt: optional header carrying group membership. In
+     * trusted-header mode the value is split on comma; in jwt mode this overrides
+     * the claim source only when the proxy passes groups as a header (rare).
+     */
+    groupsHeader?: string;
+    /** jwt: header carrying the token. `Authorization` strips a leading `Bearer `. */
+    jwtHeader: string;
+    /** jwt: JWKS endpoint used to verify the token signature (required in jwt mode). */
+    jwksUrl?: string;
+    /** jwt: expected `iss` claim (validated when set). */
+    jwtIssuer?: string;
+    /** jwt: expected `aud` claim (validated when set). */
+    jwtAudience?: string;
+    /** jwt: claim to read the username from (falls back preferred_username→email→sub). */
+    usernameClaim?: string;
+    /** jwt: claim to read groups from (default `groups`). */
+    groupsClaim: string;
+}
+/**
+ * Per-instance branding (issue #34). Lets several Paddock instances (Projects,
+ * Homelab, House, …) be told apart at a glance. All optional; the defaults
+ * preserve today's look (🐎 / "Paddock" / terracotta). Injected into index.html
+ * at serve time (so there's no title/color flash) and read by the SPA from a
+ * `window.__PADDOCK_CONFIG__` global.
+ */
+export interface BrandConfig {
+    /** Wordmark shown top-left and as the browser tab title. */
+    name: string;
+    /** Logo: an emoji/glyph, OR a URL/absolute path to an image (rendered as <img>). */
+    logo: string;
+    /** Accent color as a hex string driving the primary buttons + logo chip. */
+    accent: string;
+}
+/** OpenAPI / Swagger-UI reference surface config (see PaddockConfig.openapi). */
+export interface OpenApiConfig {
+    /** Mount the `/open-api` UI + `/open-api.json` spec. Opt-in — defaults false. */
+    enabled: boolean;
+    /** Route prefix the UI is served under (raw spec at `<path>.json`). */
+    path: string;
+}
+export interface PaddockConfig {
+    /** HTTP/WS port. */
+    port: number;
+    /** Bind host. Defaults to loopback (`127.0.0.1`) — safe by default (#435). */
+    host: string;
+    /**
+     * Dangerously opt in to an OPEN, unauthenticated server: allow a non-loopback
+     * bind while `auth.mode === "none"` (which the bind-safety guard otherwise
+     * refuses). Driven by `PADDOCK_DANGEROUSLY_ALLOW_OPEN`; accepts 1/true/yes.
+     */
+    dangerouslyAllowOpen: boolean;
+    /** Absolute (canonical) path to the data root. Holds state files (e.g. sweep). */
+    dataDir: string;
+    /** Absolute path to the root that contains per-project directories. */
+    projectsRoot: string;
+    /** Absolute path to the herdctl state directory (.herdctl). */
+    stateDir: string;
+    /**
+     * Absolute path to the generated herdctl.yaml that the FleetManager loads.
+     * Paddock owns/regenerates this file (one keeper agent per project).
+     */
+    herdctlConfigPath: string;
+    /** Absolute path to the built web SPA (served in production). */
+    webDist: string;
+    /**
+     * Absolute path to the Claude home (`~/.claude`, unless `CLAUDE_HOME` says
+     * otherwise) — the directory whose `projects/<encoded-cwd>/` folders hold
+     * Claude Code's session transcripts.
+     *
+     * Resolved ONCE here (#588) rather than re-read from `process.env` at each call
+     * site, because it must be the SAME value everywhere: paddock's transcript
+     * relocation (`ensureProjectChats`) symlinks `<claudeHome>/projects/<encoded>`
+     * at the project's `.chats/`, and the engine's session discovery / adoption
+     * resolves transcripts under `FleetManagerOptions.claudeHomePath`. If paddock
+     * honoured `CLAUDE_HOME` while the engine fell back to `os.homedir()/.claude`,
+     * detection would scan one home while reads came from another — chats LIST but
+     * open EMPTY (herdctl#423 / #588 gotcha 1). The divergence is invisible
+     * whenever `CLAUDE_HOME` equals `$HOME/.claude`, which is exactly why it is
+     * threaded explicitly instead of being left to a shared default.
+     */
+    claudeHome: string;
+    /** Provider-agnostic user-authentication config (see AUTH.md). */
+    auth: AuthConfig;
+    /** Voice-dictation (Whisper) capability (per-instance; default off). */
+    transcription: TranscriptionConfig;
+    /** Per-instance branding (title/logo/accent; defaults preserve today's look). */
+    brand: BrandConfig;
+    /**
+     * OpenAPI / Swagger-UI reference (the `/open-api` docs + `/open-api.json`
+     * spec, derived from the route schemas). `enabled` mounts or omits the whole
+     * surface. Driven by `PADDOCK_OPENAPI_ENABLED` (1/true/yes/on enable);
+     * default OFF (opt-in) — publishing the API surface map is a deliberate
+     * choice. Gated by the instance auth mode like any other route when enabled.
+     */
+    openapi: OpenApiConfig;
+    /**
+     * Global default for how keeper chat turns are driven (Paddock#111), used when
+     * a project doesn't override `driveMode`. `session` by default (#316) — the
+     * persistent `openChatSession` path, so cross-turn autonomy (ScheduleWakeup /
+     * `/loop`) and SDK streaming work out of the box; set
+     * `PADDOCK_DRIVE_MODE=batch` for the legacy one-shot `trigger()` path.
+     */
+    driveMode: DriveMode;
+    /**
+     * The instance ALLOW-LIST of offered models (issue #457 Step 2), by catalog id
+     * — which of the built-in {@link import("./models.js").MODELS} catalog the model
+     * picker + per-project default offer. `undefined` (the default, when neither
+     * `PADDOCK_MODELS` nor a YAML `models:` list is set) means "offer every catalog
+     * model" — fully backward-compatible. When set it is a validated, de-duped subset
+     * (unknown ids dropped; an empty result collapses back to the full catalog, so an
+     * instance never offers zero models). The catalog itself stays the source of each
+     * model's metadata and of {@link import("./models.js").isKnownModel}; this only
+     * narrows what's OFFERED. Resolved to concrete {@link ModelInfo} via
+     * {@link import("./models.js").resolveModels}. A per-project `models` override can
+     * narrow it further (never widen beyond this list).
+     */
+    models?: string[];
+    /**
+     * Whether keeper agents use the native Claude Code system prompt +
+     * project CLAUDE.md hierarchy (true, the default) instead of a terse Paddock
+     * "replace" system prompt (false). Driven by `PADDOCK_NATIVE_PROMPT`.
+     *
+     * This is its own decision (issue #176) governing only which system prompt an
+     * agent gets. When native (the default on every instance) Paddock sets NO
+     * `system_prompt`, so 100% of an agent's standing instructions come from
+     * Claude Code's own `CLAUDE.md` walk-up from its cwd — which is what makes the
+     * cwd load-bearing. Set `PADDOCK_NATIVE_PROMPT=false` to fall back to
+     * the terse replace prompt (e.g. an instance with no CLAUDE.md files).
+     *
+     * **The canonical instance-wide `CLAUDE.md` is `<projectsRoot>/CLAUDE.md`**
+     * (issue #512). `projectsRoot` IS the instance's backing repo, so that file is
+     * version-controlled and pushed with everything else, whereas a
+     * `<dataDir>/CLAUDE.md` would sit outside the repo. It reaches every project
+     * keeper by walk-up (a project dir is a child of `projectsRoot`) and the ROOT
+     * keeper too — the root workspace's cwd IS `projectsRoot`. There is no longer
+     * any agent whose cwd sits outside that tree, so every keeper picks the
+     * instance CLAUDE.md up by walk-up. That closes #512.
+     */
+    nativeSystemPrompt: boolean;
+    /**
+     * The **environment** prompt appended to every keeper turn's system prompt
+     * (issue #635) — the short note telling the agent it renders into a browser as
+     * GFM, not a terminal. Resolved from `PADDOCK_ENVIRONMENT_PROMPT` over the
+     * `environmentPrompt:` file key over
+     * {@link import("./environment-prompt.js").DEFAULT_ENVIRONMENT_PROMPT}.
+     *
+     * This is the RESOLVED, effective text, so it has only two meaningful states
+     * at the point of use: non-empty (append it) and `""` (append nothing — the
+     * instance opted out). The three *authoring* states — unset, a string, an
+     * empty string — collapse here, which is deliberate: every consumer just asks
+     * "is there anything to append?" and the Settings screen shows the text that
+     * is actually in force rather than a tri-state it would have to explain.
+     *
+     * Orthogonal to {@link nativeSystemPrompt}: that switch chooses the agent's
+     * *role* prompt (native preset vs Paddock's terse replace text); this states
+     * environmental fact about the deployment and applies on top of either.
+     */
+    environmentPrompt: string;
+    /**
+     * Whether keeper turns are handed the read-only self-management MCP server
+     * (issue #214 Phase 1) — the `mcp__paddock_manage__*` tools that let a keeper
+     * enumerate projects/chats and read another chat's transcript. Driven by
+     * `PADDOCK_SELF_MCP`; default OFF (opt-in per instance). The write tools
+     * (create/fork/message) are gated separately by
+     * {@link selfMcpWriteEnabled}.
+     */
+    selfMcpEnabled: boolean;
+    /**
+     * Whether keepers additionally get the self-management MCP **write** tools
+     * (issue #214 Phase 2) — `create_chat`, `fork_chat`, `send_message`,
+     * `fork_chat_batch` (fan-out). Driven by `PADDOCK_SELF_MCP_WRITE`; default OFF
+     * and only honored when {@link selfMcpEnabled} is also on (write implies read).
+     * Gated behind its own flag because these START real keeper turns — an instance
+     * can offer read-only introspection without the write blast radius.
+     */
+    selfMcpWriteEnabled: boolean;
+    /**
+     * Whether keepers additionally get the self-management MCP **project** tools
+     * (issue #467) — `create_project`, which provisions a whole new project
+     * (directory + `project.yaml`, optionally a cloned repo-backed checkout) and
+     * registers its keeper agent. Driven by `PADDOCK_SELF_MCP_PROJECTS`; default OFF
+     * and only honored when {@link selfMcpWriteEnabled} is also on (the tool lives in
+     * the write block).
+     *
+     * Gated behind its OWN flag rather than folded into `selfMcpWriteEnabled` because
+     * every other write tool acts WITHIN an existing project, whereas this one mutates
+     * instance-level state (a new dir in the projects root, new long-lived agents) and
+     * runs `git clone` on a CALLER-SUPPLIED url. It is an operator-intent boundary, not
+     * a hard security one (a keeper with Bash in a write-enabled project can already
+     * clone what it likes) — but provisioning infrastructure should be opt-in.
+     */
+    selfMcpProjectsEnabled: boolean;
+    /**
+     * Instance default for how deep a spawn tree may grow before spawned children
+     * stop receiving the self-management MCP (issue #262 / DD-3). A spawned turn at
+     * depth `d` gets the self-MCP (incl. write tools, so `send_message` exists and a
+     * child can report back to its parent) iff `d <= maxSpawnDepth`. Driven by
+     * `PADDOCK_MAX_SPAWN_DEPTH`; default {@link DEFAULT_MAX_SPAWN_DEPTH} (`1` — a
+     * manager's direct children work, grandchildren are blocked). `0` restores
+     * today's behaviour (no spawned child gets it). A per-project `maxSpawnDepth`
+     * overrides this at dispatch (the `driveMode` pattern). Only meaningful when
+     * {@link selfMcpWriteEnabled} is on — spawning needs the write tools.
+     */
+    maxSpawnDepth: number;
+    /**
+     * Per-deployment gate for programmatic schedule mutation (issue #265 / DD-7).
+     * When ON, the FleetManager is constructed with `allowScheduleMutation: true`,
+     * so herdctl's runtime schedule add/remove APIs (the
+     * seam the D4 schedules UI calls) are permitted; OFF (default) makes them throw.
+     * Declaring schedules statically in `project.yaml` is unaffected either way.
+     * Driven by `PADDOCK_SCHEDULE_MUTATION`; accepts 1/true/yes.
+     */
+    scheduleMutationEnabled: boolean;
+    /**
+     * External Management API clients (issue #312 M1) — the `/mcp` surface for
+     * callers OUTSIDE this instance (a laptop Claude Code session, a peer Paddock).
+     *
+     * Self-contained and INDEPENDENT of {@link auth}: `/mcp` authenticates itself,
+     * so it stays credential-gated even at `auth.mode: none`, and needs no reverse
+     * proxy. An EMPTY client list means the surface is off entirely and `/mcp`
+     * 404s — the endpoint does not exist until deliberately configured.
+     */
+    managementApi: ManagementApiConfig;
+    /**
+     * Operator-facing problems found while resolving {@link managementApi} — a
+     * malformed client (`errors`) or one dropped because its credential wouldn't
+     * resolve (`warnings`). Carried on the config rather than logged at parse time
+     * because config loading has no logger; app.ts logs these at boot.
+     */
+    managementApiDiagnostics: {
+        errors: string[];
+        warnings: string[];
+    };
+    /**
+     * Instance default for the hook-management MCP (Epic G / G5, GG-4) — the
+     * `mcp__paddock_manage__{list,set,remove}_hook` tools that let a project agent
+     * declare/edit/delete its own event hooks. A sibling of {@link selfMcpWriteEnabled}:
+     * OFF by default (opt-in), and only surfaces when the self-MCP write tools are also
+     * present (the hook tools live on the same injected server, appended in the write
+     * block). Driven by `PADDOCK_HOOKS_MCP`; accepts 1/true/yes. A per-project
+     * `hooksMcpEnabled` override wins at dispatch (resolved via
+     * {@link import("./hook-config.js").resolveHooksMcpEnabled}), the same
+     * inherit/override discipline as `maxSpawnDepth`. The gate is BINARY access to the
+     * MCP — an agent that has it can create hooks at any capability (GG-4: no
+     * per-capability gating).
+     */
+    hooksMcpEnabled: boolean;
+    /**
+     * Keeper-chat recovery config (issue #301) — the two independently-toggleable
+     * layers that unstick a keeper whose background task is killed at the turn
+     * boundary (see recovery-config.ts / edspencer/herdctl#374). Instance defaults
+     * here (`PADDOCK_RECOVERY_*` env, YAML beneath); a per-project `recovery`
+     * override wins at dispatch via
+     * {@link import("./recovery-config.js").resolveRecoveryConfig}. Layer 2
+     * (`surfaceKilledTask`) defaults ON; Layer 3 (`autoReDrive`) defaults OFF.
+     */
+    recovery: RecoveryConfig;
+    /**
+     * Inbound composer-attachment config (issue #328) — whether users can upload
+     * files/images into the composer, and the size/count/type caps. Instance
+     * defaults here (`PADDOCK_ATTACHMENTS_*` env, YAML beneath); a per-project
+     * `attachments` override wins at request time via
+     * {@link import("./attachments-config.js").resolveAttachmentsConfig}. Enabled +
+     * allow-all by default.
+     */
+    attachments: AttachmentsConfig;
+    /**
+     * Per-file token budgets the post-turn sweeper (curation) must keep its three
+     * curated files under (issue #379). These bound the context every keeper chat
+     * pays for — CHANGELOG.md + OVERVIEW.md are injected into the project-context
+     * preload, and CLAUDE.md auto-loads every turn. The sweeper is told each budget
+     * (so it prunes/dedups to fit) and `SweepService` enforces it as a backstop.
+     * Instance defaults here (`PADDOCK_CURATION_*` env, YAML beneath).
+     */
+    curation: CurationConfig;
+    /**
+     * Log level for the server's structured logger (Fastify/pino). Driven by
+     * `LOG_LEVEL`; default `info`.
+     */
+    logLevel: string;
+    /**
+     * Whether keeper agents receive the Playwright browser MCP server
+     * (headless Chromium) so Claude Code can drive a browser (navigate / click /
+     * snapshot / screenshot). Driven by `PADDOCK_BROWSER_MCP` (`1` enables);
+     * default false. Scoped PER INSTANCE — a box without the browser stack leaves
+     * it off so there are no failed spawns, and enabling it is a per-box env flip.
+     */
+    browserMcp: boolean;
+    /**
+     * Minimum ms between post-turn curation sweeps for a single project, or
+     * `undefined` to use the SweepService default (5 min). Driven by
+     * `PADDOCK_SWEEP_MIN_INTERVAL_MS`; a non-finite or negative value is ignored
+     * (falls back to the default).
+     */
+    sweepMinIntervalMs?: number;
+    /**
+     * Git commit identity used when Paddock commits on a project's behalf, so no
+     * global git config is needed. Driven by `PADDOCK_GIT_AUTHOR_NAME` /
+     * `PADDOCK_GIT_AUTHOR_EMAIL`; defaults `Paddock` / `paddock@localhost`.
+     */
+    gitAuthor: {
+        name: string;
+        email: string;
+    };
+    /**
+     * The GitHub OAuth/App client id for the git-backing-store device flow
+     * (github-auth.ts). Driven by `PADDOCK_GITHUB_CLIENT_ID`; `undefined` when
+     * unset, in which case the GitHub connect feature reports "not configured".
+     */
+    githubClientId?: string;
+}
+/**
+ * On-disk shape of the optional YAML instance-config file (issue #270 / DD-5).
+ *
+ * This is the BASE layer for {@link PaddockConfig}: every field is optional and
+ * a matching `PADDOCK_*` env var still overrides it (precedence file < env), so
+ * an env-only deployment is unaffected when no file is present. Values mirror
+ * the resolved config's structure; scalars accept their natural YAML type (and
+ * also a string, since each value is coerced through the same env-parsing path).
+ * Unknown keys are ignored — later epics (schedules, hooks) will add their own
+ * top-level record sections here.
+ */
+export interface PaddockConfigFile {
+    port?: number | string;
+    host?: string;
+    dataDir?: string;
+    projectsRoot?: string;
+    stateDir?: string;
+    herdctlConfigPath?: string;
+    webDist?: string;
+    auth?: {
+        mode?: string;
+        userHeader?: string;
+        emailHeader?: string;
+        groupsHeader?: string;
+        jwtHeader?: string;
+        jwksUrl?: string;
+        jwtIssuer?: string;
+        jwtAudience?: string;
+        usernameClaim?: string;
+        groupsClaim?: string;
+    };
+    transcription?: {
+        mode?: string;
+        model?: string;
+        endpoint?: string;
+        apiKey?: string;
+        language?: string;
+        maxUploadBytes?: number | string;
+    };
+    brand?: {
+        name?: string;
+        logo?: string;
+        accent?: string;
+    };
+    openapi?: {
+        enabled?: boolean | string;
+        path?: string;
+    };
+    /**
+     * Instance allow-list of offered models (issue #457 Step 2). A real array of
+     * catalog ids (or a comma-separated string, coerced the same way); a matching
+     * `PADDOCK_MODELS` env var (comma-separated) still overrides it (file < env).
+     * Absent ⇒ every catalog model is offered (unchanged behaviour).
+     */
+    models?: string[] | string;
+    driveMode?: string;
+    nativeSystemPrompt?: boolean | string;
+    /**
+     * Environment system prompt override (issue #635). Absent ⇒ Paddock's built-in
+     * text; a non-empty string ⇒ that text instead; an EMPTY string ⇒ append
+     * nothing. Unlike almost every other key here, blank is meaningful and is NOT
+     * folded to the default — see {@link loadEnvironmentPrompt}.
+     */
+    environmentPrompt?: string;
+    selfMcpEnabled?: boolean | string;
+    selfMcpWriteEnabled?: boolean | string;
+    selfMcpProjectsEnabled?: boolean | string;
+    maxSpawnDepth?: number | string;
+    scheduleMutationEnabled?: boolean | string;
+    hooksMcpEnabled?: boolean | string;
+    /**
+     * External Management API config (issue #312 M1). Token material is given as
+     * an `env:VAR_NAME` REFERENCE — never inlined, because this file is
+     * git-tracked. Absent ⇒ no external clients ⇒ `/mcp` 404s (fail closed).
+     */
+    managementApi?: ManagementApiConfigFile;
+    /**
+     * Keeper-chat recovery config (issue #301). Every field optional; a matching
+     * `PADDOCK_RECOVERY_*` env var still overrides it (precedence file < env).
+     */
+    recovery?: {
+        surfaceKilledTask?: boolean | string;
+        autoReDrive?: boolean | string;
+        debounceMs?: number | string;
+        maxRetries?: number | string;
+        limboTimeoutMs?: number | string;
+    };
+    /**
+     * Inbound composer-attachment config (issue #328). Every field optional; a
+     * matching `PADDOCK_ATTACHMENTS_*` env var still overrides it (file < env).
+     * `allowedTypes` is a real array here (env is comma-separated).
+     */
+    attachments?: {
+        enabled?: boolean | string;
+        maxFileSizeMb?: number | string;
+        maxFilesPerMessage?: number | string;
+        allowedTypes?: string[] | string;
+    };
+    /**
+     * Per-file curation token budgets (issue #379). Every field optional; a
+     * matching `PADDOCK_CURATION_*` env var still overrides it (file < env).
+     */
+    curation?: {
+        overviewMaxTokens?: number | string;
+        changelogMaxTokens?: number | string;
+        claudeMaxTokens?: number | string;
+    };
+    logLevel?: string;
+    browserMcp?: boolean | string;
+    sweepMinIntervalMs?: number | string;
+    gitAuthor?: {
+        name?: string;
+        email?: string;
+    };
+    githubClientId?: string;
+}
+/**
+ * Voice-dictation (Whisper) capability. Mirrors HushPod's whisper config so the
+ * two can share a transcription backend (e.g. Ed's laptop whisper server). Driven
+ * entirely by `PADDOCK_WHISPER_*` env so it is scoped PER INSTANCE and defaults
+ * to `off` — a plain instance advertises no mic button.
+ *
+ * - `off`    — dictation disabled (default). No mic button in the composer.
+ * - `remote` — POST audio to an OpenAI-compatible `/audio/transcriptions`
+ *              endpoint (e.g. `http://whisper.local:8385/v1`). The same kind of
+ *              server HushPod points at.
+ * - `local`  — run whisper.cpp on this box via nodejs-whisper (CPU; slower).
+ */
+export type WhisperMode = "off" | "local" | "remote";
+export interface TranscriptionConfig {
+    /** Dictation backend. `off` disables the composer mic button. */
+    mode: WhisperMode;
+    /** Whisper model name (e.g. `base`, `base.en`, `small`). */
+    model: string;
+    /**
+     * remote: OpenAI-compatible base URL, e.g. `http://whisper.local:8385/v1`.
+     * `/audio/transcriptions` is appended. Required in `remote` mode.
+     */
+    endpoint?: string;
+    /** remote: optional bearer token sent as `Authorization: Bearer …`. */
+    apiKey?: string;
+    /** Optional spoken-language hint (ISO-639-1, e.g. `en`). Unset ⇒ auto-detect. */
+    language?: string;
+    /** Max accepted upload size in bytes (guards the transcribe route). */
+    maxUploadBytes: number;
+}
+/**
+ * Load the optional YAML instance-config file that provides the BASE layer for
+ * {@link PaddockConfig} (issue #270 / DD-5). Env vars still override every value
+ * (precedence file < env).
+ *
+ * Path resolution: an explicit `PADDOCK_CONFIG` env var wins; otherwise
+ * `<dataDir>/paddock.config.yaml`. When no file exists at the default location
+ * the result is an empty object, so an env-only deployment behaves exactly as
+ * before — this is a no-op for existing installs. An explicit `PADDOCK_CONFIG`
+ * that points at a missing file is treated as a misconfiguration (a clear error)
+ * rather than silently ignored.
+ *
+ * A present-but-malformed file (unparseable YAML, or a top-level scalar/list
+ * instead of a mapping) throws a clear Error rather than starting up with a
+ * half-empty config.
+ */
+export declare function loadConfigFile(dataDir: string): PaddockConfigFile;
+/**
+ * Default location of the built web SPA, resolved RELATIVE TO THIS MODULE:
+ * `packages/server/{src,dist}/config.js` -> `packages/web/dist`. The same hop
+ * works from both the `tsx src/` and `node dist/` layouts, so neither needs a
+ * `PADDOCK_WEB_DIST` override.
+ *
+ * Takes the module URL as a parameter purely so a test can exercise install
+ * paths this repo's own checkout does not have.
+ *
+ * **`fileURLToPath`, NOT `new URL(url).pathname`.** The raw pathname is
+ * percent-ENCODED, so an install path containing a space or any non-ASCII
+ * character (`/opt/my paddock/`, `~/Développement/`) yields a literal `%20`
+ * that resolves to a directory which does not exist. The failure is SILENT:
+ * `app.ts` degrades to API-only mode with only a log warning, so the user gets
+ * a blank page and no explanation of why. `fileURLToPath` also decodes the
+ * `/C:/...` drive-letter form on Windows. This is irrelevant when the path is
+ * the Docker image's fixed `/app`, and load-bearing the moment the package is
+ * installed under an arbitrary user directory (`npx`, global install).
+ */
+export declare function resolveDefaultWebDist(moduleUrl: string): string;
+export declare function loadPaddockConfig(): PaddockConfig;
+/**
+ * Resolve the Claude home from the environment — `CLAUDE_HOME`, else
+ * `~/.claude`.
+ *
+ * This is the RESOLVER, not the accessor. It is read once by
+ * {@link loadPaddockConfig} into {@link PaddockConfig.claudeHome}; runtime code
+ * should thread `cfg.claudeHome` rather than call this again, so paddock and the
+ * engine can never end up resolving two different homes (#588). It stays a
+ * function (not a constant) because `os.homedir()` must be read at call time —
+ * tests and processes that mutate `HOME` depend on that.
+ */
+export declare function claudeHome(): string;