@inkeep/open-knowledge 0.58.0-beta.0 → 0.58.0-beta.10

package/dist/index.d.mts

@@ -1130,14 +1130,14 @@ type _File = typeof globalThis extends {
   File: infer F extends new (...args: any[]) => any;
 } ? InstanceType<F> : {};
 /** Do not reference this directly. */
-interface File extends _File {
+interface File$1 extends _File {
   readonly type: string;
   readonly size: number;
 }
 interface $ZodFileDef extends $ZodTypeDef {
   type: "file";
 }
-interface $ZodFileInternals extends $ZodTypeInternals<File, File> {
+interface $ZodFileInternals extends $ZodTypeInternals<File$1, File$1> {
   def: $ZodFileDef;
   isst: $ZodIssueInvalidType;
   bag: LoosePartial<{
@@ -2095,6 +2095,8 @@ declare const ZodNumber: $constructor<ZodNumber>;
 interface _ZodBoolean<T extends $ZodBooleanInternals = $ZodBooleanInternals> extends _ZodType<T> {}
 interface ZodBoolean extends _ZodBoolean<$ZodBooleanInternals<boolean>> {}
 declare const ZodBoolean: $constructor<ZodBoolean>;
+interface ZodNull extends _ZodType<$ZodNullInternals> {}
+declare const ZodNull: $constructor<ZodNull>;
 interface ZodUnknown extends _ZodType<$ZodUnknownInternals> {}
 declare const ZodUnknown: $constructor<ZodUnknown>;
 interface ZodArray<T extends SomeType = $ZodType> extends _ZodType<$ZodArrayInternals<T>>, $ZodArray<T> {
@@ -2227,6 +2229,20 @@ interface ZodReadonly<T extends SomeType = $ZodType> extends _ZodType<$ZodReadon
 }
 declare const ZodReadonly: $constructor<ZodReadonly>;
 //#endregion
+//#region ../core/src/bug-report-sidecar/schema.d.ts
+/**
+ * Known report lifecycle states. Read as an OPEN enum: an unrecognized value
+ * (a newer app wrote a state this build doesn't know) normalizes to `'unknown'`
+ * rather than rejecting the sidecar. Transitions:
+ *   generated → uploading → sent (+reference) | upload-failed (+lastError) | email-drafted
+ * A retry moves a non-`sent` report back to `uploading` and on to a terminal
+ * state again.
+ */
+declare const REPORT_SIDECAR_STATES: readonly ["generated", "uploading", "sent", "upload-failed", "email-drafted"];
+type ReportSidecarKnownState = (typeof REPORT_SIDECAR_STATES)[number];
+/** The known states plus the `'unknown'` sentinel a read may normalize to. */
+type ReportSidecarState = ReportSidecarKnownState | 'unknown';
+//#endregion
 //#region ../core/src/logger-types.d.ts
 interface BundleRedaction {
   readonly file: string;
@@ -2258,6 +2274,231 @@ interface ReportBundleSummary$1 {
   redactedLineCount: number;
   generatedAt: string;
 }
+/**
+ * A captured picture of the app window handed to the renderer for the report
+ * dialog's include-a-screenshot preview. `dataUrl` is a downscaled PNG for the
+ * `<img>` preview only; the full-resolution bytes stay in main and are staged
+ * into the bundle only when the user keeps the screenshot checked. `width` /
+ * `height` are the capture's logical (DIP) dimensions, so the preview can hold
+ * the real aspect ratio without a layout shift.
+ */
+interface OkBugReportScreenshot {
+  dataUrl: string;
+  width: number;
+  height: number;
+}
+/**
+ * Result of the desktop `ok:bug-report:dispatch` create operation. Never
+ * thrown across the IPC boundary — every failure mode is discriminated so the
+ * report dialog can render its failure state.
+ */
+type OkBugReportCreateResult = {
+  ok: true;
+  zipPath: string;
+  /**
+   * On-disk size of the produced zip. Carried on the result rather than
+   * the summary because the summary mirrors the bundled manifest, which
+   * cannot know the final size of the archive that contains it.
+   */
+  zipSizeBytes: number;
+  summary: ReportBundleSummary$1;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Report metadata the renderer supplies with a send operation — the user's
+ * note plus the system summary the preceding create yielded. Main enriches
+ * it with host facts (app version, platform) before it reaches the intake
+ * wire or the fallback email body; the renderer never sources those.
+ */
+interface OkBugReportSendMetadata {
+  level: ReportBundleLevel$1;
+  /** True when the bundle was system-wide (no project open at capture). */
+  systemWide: boolean;
+  projectSlug: string | null;
+  note?: string;
+}
+/**
+ * Why a send operation resolved to the email fallback instead of an upload
+ * reference. `email-draft` is the designed default, not a failure: no intake
+ * endpoint is configured, no network request was made, and the prefilled
+ * draft IS the transport — the dialog shows an email flow, not an error.
+ * `send-failed` covers real failures: a configured upload that was attempted
+ * and refused (offline, timeout, rejection at any step), or a request the
+ * handler refused outright (malformed payload, zip outside the bug-reports
+ * root).
+ */
+type OkBugReportSendFallbackReason = 'email-draft' | 'send-failed';
+/**
+ * Result of the desktop `ok:bug-report:dispatch` send operation. Success
+ * carries the intake service's report reference. Everything else resolves to
+ * the email fallback — a prefilled mailto the dialog offers in place of the
+ * upload — with `reason` discriminating the designed no-intake email path
+ * from a genuine send failure. Never thrown across the IPC boundary.
+ */
+type OkBugReportSendResult = {
+  ok: true;
+  reference: string;
+} | {
+  ok: false;
+  reason: OkBugReportSendFallbackReason;
+  fallback: {
+    mailtoUrl: string;
+  };
+};
+/**
+ * A crash signal detected by desktop main, pushed to the renderer over the
+ * `ok:bug-report:crash-detected` event channel as an invitation to file a
+ * report — never an automatic send. `eventId` keys the acknowledgment
+ * round-trip: the renderer acks over `ok:bug-report:dispatch`
+ * (`kind: 'crash-ack'`) and main persists the id so one crash event never
+ * prompts twice, across restarts included.
+ *
+ * Lives in core for the same reason as the sibling bug-report types: the
+ * desktop-bridge leaf and the capture implementation must share one type.
+ *
+ * `minidumpAvailable` is main's authoritative answer (only main can stat the
+ * crash-dumps dir) to "is there a crash minidump to include for this event?".
+ * The report dialog renders the crash-dump opt-in only when it is true — an
+ * invite with no dump (e.g. a dirty shutdown that left none) offers no dead
+ * checkbox. Advisory for UI gating only: the actual attach still re-checks the
+ * dump on disk at bundle time, so a dump that vanished by then is simply
+ * omitted.
+ */
+type OkBugReportCrashDetectedEvent = {
+  eventId: string;
+  kind: 'render-process-gone';
+  context: {
+    reason: string;
+    exitCode?: number;
+  };
+  minidumpAvailable: boolean;
+} | {
+  eventId: string;
+  kind: 'child-process-gone';
+  context: {
+    reason: string;
+    processType: string;
+    name?: string;
+    exitCode?: number;
+  };
+  minidumpAvailable: boolean;
+} | {
+  eventId: string; /** Boot-time detection: the previous session left a dirty-shutdown sentinel or fresh minidumps. */
+  kind: 'boot';
+  context: {
+    dirtyShutdown: boolean;
+    newMinidumps: number;
+  };
+  minidumpAvailable: boolean;
+  /**
+   * App version of the session that CRASHED, which is not the version now
+   * running whenever an auto-update landed between the crash and this
+   * launch. Absent when neither the crashed session's sentinel nor the
+   * minidump's own annotations name one — an unknown version is reported
+   * as unknown rather than approximated by the running one.
+   *
+   * Only the boot variant carries it. The two runtime variants are raised
+   * by the very session that crashed, so their crashed version is the
+   * running version by construction and a field would be pure restatement.
+   */
+  crashedAppVersion?: string;
+};
+/**
+ * Result of the desktop `ok:bug-report:dispatch` crash-ack operation. Never
+ * thrown across the IPC boundary; the only failure mode is a malformed
+ * renderer payload.
+ */
+type OkBugReportCrashAckResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Whether main is holding a crash dump a report opened right now could carry.
+ *
+ * Deliberately a bare boolean: which dump, when it was written, and how big it
+ * is are all per-crash identifiers, and the renderer only needs to decide
+ * whether to render the opt-in.
+ */
+interface OkBugReportCrashDumpAvailability {
+  available: boolean;
+}
+/**
+ * One row in the persisted bug-report history, projected from a report sidecar
+ * plus main-derived facts. `state` is the OPEN sidecar state (`'unknown'` for a
+ * degraded/legacy/corrupt row). `zipPath` is main-derived (never renderer
+ * influenced) and re-validated for containment before any retry/reveal; the
+ * renderer passes it straight back to `send` / reveal without composing a path.
+ *
+ * `systemWide` / `projectSlug` are carried so a retry reconstructs the exact
+ * `OkBugReportSendMetadata` without a second capture. `retryable` is
+ * `true` only when the report is neither `sent` nor mid-`uploading` and its zip
+ * is still on disk. `degraded` is `true` for a synthesized row (no sidecar, a
+ * corrupt sidecar, or an unknown state) so the list can render it plainly
+ * instead of failing.
+ */
+interface OkBugReportListRow {
+  id: string;
+  createdAt: string;
+  bundleLevel: ReportBundleLevel$1 | 'unknown';
+  /**
+   * Derived from the sidecar's single-source state list, so a state added to
+   * `REPORT_SIDECAR_STATES` propagates here instead of silently drifting.
+   */
+  state: ReportSidecarState;
+  zipBytes: number;
+  zipDeleted: boolean;
+  zipExists: boolean;
+  systemWide: boolean;
+  projectSlug: string | null;
+  /**
+   * State-coupled: present only when `state === 'sent'`. Not modelled as a
+   * discriminated union because `state` is an OPEN enum — enumerating arms
+   * here would reintroduce the drift that deriving `state` removes.
+   */
+  reference?: string;
+  /** State-coupled: present only when `state === 'upload-failed'`. */
+  lastError?: {
+    reason: string;
+    at: string;
+  };
+  attemptsCount: number;
+  note?: string;
+  /** Main-derived absolute zip path; re-validated for containment on use. */
+  zipPath: string;
+  retryable: boolean;
+  degraded: boolean;
+}
+/**
+ * Result of the desktop `ok:bug-report:dispatch` list operation — the persisted
+ * report history, newest first. Never thrown across the IPC boundary; a scan
+ * failure resolves to `{ ok: false }` so the list renders an error state.
+ */
+type OkBugReportListResult = {
+  ok: true;
+  reports: OkBugReportListRow[];
+} | {
+  ok: false;
+  reason: string;
+};
+/**
+ * Result of the desktop `ok:bug-report:dispatch` delete operation. Removes a
+ * report's zip and sidecar by `id` after a containment + id-shape check. Never
+ * thrown across the IPC boundary.
+ *   - `id-invalid`  — the id failed the timestamp-basename shape / containment gate.
+ *   - `in-flight`   — the report's own send is currently in progress in this process.
+ *   - `not-found`   — no zip and no sidecar for the id.
+ *   - `io-error`    — a filesystem removal failed.
+ */
+type OkBugReportDeleteResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: 'id-invalid' | 'in-flight' | 'not-found' | 'io-error';
+};
 //#endregion
 //#region ../core/src/logging/secret-scrub.d.ts
 /** Apply {@link SECRET_PATTERNS} line by line; report which patterns matched. */
@@ -4236,6 +4477,19 @@ interface IgnoredCommittedKey {
   source?: ConfigIssueSource;
 }
 //#endregion
+//#region ../core/src/constants/create-new-banner.d.ts
+/**
+ * Cascade-banner discriminator for the Create new project dialog. Drives:
+ *   - the renderer's banner-shown telemetry dedup (one per dialog open)
+ *   - the main-process recordCreateNewBannerShown handler's banner attribute
+ *   - the corresponding span attribute on ok.desktop.createNewBannerShown
+ *
+ *  - `'nested'`      — banner shown when parent is inside an existing OK project.
+ *  - `'nonempty'`    — banner shown when target folder exists with content.
+ *  - `'git-confirm'` — banner shown when parent is inside a git repo (no .ok/).
+ */
+type CreateNewBannerKind = 'nested' | 'nonempty' | 'git-confirm';
+//#endregion
 //#region ../core/src/constants/editors.d.ts
 /**
  * Canonical editor-ID and label registry shared across the CLI's
@@ -4247,6 +4501,19 @@ interface IgnoredCommittedKey {
  */
 type EditorId$1 = 'claude' | 'claude-desktop' | 'cursor' | 'codex' | 'copilot' | 'opencode' | 'openclaw' | 'pi' | 'antigravity' | 'lm-studio' | 'hermes';
 //#endregion
+//#region ../core/src/constants/folder-state.d.ts
+/**
+ * Classification of a candidate folder path. Drives the renderer's banner
+ * cascade and the IPC handler's defense-in-depth check.
+ *
+ *  - `'free'`             — path does not exist on disk; safe to mkdir.
+ *  - `'exists-empty'`     — directory exists with zero entries; safe to use.
+ *  - `'exists-nonempty'`  — directory exists with at least one entry, OR the
+ *                           path resolves to a non-directory (a file occupies
+ *                           the name). Either case blocks the create.
+ */
+type OkFolderState = 'free' | 'exists-empty' | 'exists-nonempty';
+//#endregion
 //#region ../../node_modules/.pnpm/prosemirror-transform@1.12.0/node_modules/prosemirror-transform/dist/index.d.ts
 /**
 There are several things that positions can be mapped through.
@@ -9946,6 +10213,190 @@ declare module '@tiptap/core' {
   }
 }
 //#endregion
+//#region ../core/src/git/worktree-selector-model.d.ts
+interface WorktreeSelectorEntry {
+  /** Short branch name. `null` for a detached-HEAD worktree (rare). */
+  readonly branch: string | null;
+  /**
+   * Absolute path of the worktree checked out on this branch, or `null` when
+   * no worktree exists for it yet. Realpath-collapsed by the caller.
+   */
+  readonly worktreePath: string | null;
+  /** This entry's worktree is the currently-focused window's project. */
+  readonly isCurrent: boolean;
+  /** This entry's worktree is the repo's main (primary) worktree. */
+  readonly isMain: boolean;
+  /** The worktree is locked (`git worktree lock`). */
+  readonly locked: boolean;
+  /**
+   * How many commits this local branch is behind its `origin/<branch>`
+   * upstream (READ-ONLY, no-network `git rev-list --count <branch>..origin/<branch>`
+   * at model-build). Present only when the branch HAS an upstream and the count
+   * is computable; absent (undefined) when there's no upstream, no network fetch
+   * has run, or the count couldn't be read. `0` means up-to-date with the last
+   * fetch. Surfaced as a "N behind origin" hint on the base selector to nudge the
+   * user toward a fresh `origin/<x>` base instead of a stale local one.
+   */
+  readonly behind?: number;
+}
+interface WorktreeSelectorModel {
+  /** Absolute path of the repo's main worktree (the `.ok/worktrees/` anchor). */
+  readonly mainRoot: string;
+  /** Branch of the currently-focused window's project, or `null` if unknown. */
+  readonly currentBranch: string | null;
+  /** Ordered for display: current first, then main, then the rest. */
+  readonly entries: readonly WorktreeSelectorEntry[];
+  /**
+   * Remote-tracking branch refs WITH their remote prefix (`origin/main`,
+   * `origin/feature-x`, `upstream/dev`), deduped + order-preserving,
+   * `<remote>/HEAD` symbolic refs excluded. Two consumers in the dialog:
+   *   - remote-tracking CHECKOUT: a typed `branch` whose bare name matches one
+   *     of these refs but has NO local branch is checked out as a new local
+   *     tracking branch (`git worktree add --track -b <name> <path> origin/<name>`),
+   *     NOT forked off stale HEAD (which would silently discard remote history).
+   *   - remote BASE options: every ref is selectable as a `--no-track` base for
+   *     a new branch, so a feature branch can start from fresh `origin/<x>` even
+   *     when the local `<x>` is behind.
+   * Empty when the repo has no remotes / enumeration failed (fail-soft).
+   */
+  readonly remoteBranches: readonly string[];
+}
+/**
+ * IPC-facing result of enumerating the worktree selector. Canonical here (not
+ * in desktop) so the desktop host contract and `ipc-channels` import one
+ * definition. `no-git` = the project isn't inside a git repo.
+ */
+type WorktreeListResult = {
+  readonly ok: true;
+  readonly model: WorktreeSelectorModel;
+} | {
+  readonly ok: false;
+  readonly reason: 'no-git';
+};
+/** Renderer → main request to create (or locate) a worktree for a branch. */
+interface WorktreeCreateRequest {
+  /** With `createBranch`, a NEW branch name; otherwise an existing branch. */
+  readonly branch: string;
+  /**
+   * Base ref for a new LOCAL-based branch (defaults to HEAD). Ignored unless
+   * `createBranch`, and mutually exclusive with `baseRef` (a remote base). The
+   * created branch does NOT track this base (a local base carries no upstream to
+   * inherit). Git arm: `git worktree add -b <branch> <path> -- <baseBranch>`.
+   */
+  readonly baseBranch?: string | null;
+  /**
+   * Remote-tracking base ref for a new branch (e.g. `origin/main`). Set instead
+   * of `baseBranch` when the user picked a remote base in the selector. The new
+   * branch is created off this ref WITH `--no-track` — a feature branch must not
+   * inherit the base's remote as its own upstream. Ignored unless `createBranch`;
+   * takes precedence over `baseBranch` when both are somehow set. Git arm:
+   * `git worktree add -b <branch> <path> <baseRef> --no-track`. The ref is a
+   * `<remote>/<branch>` string, never a dash-prefixed positional, so it needs no
+   * `--` guard (git resolves it as a ref, and the trailing `--no-track` is a flag).
+   */
+  readonly baseRef?: string | null;
+  /**
+   * Remote-only checkout ref (e.g. `origin/feature-x`). Set when `branch` names a
+   * branch that exists ONLY on a remote (no local branch). The worktree is checked
+   * out as a NEW LOCAL branch that TRACKS this remote ref, preserving remote
+   * history instead of forking a divergent local branch off stale HEAD. When set,
+   * `createBranch` is `true` (a local branch is created) but `baseBranch` /
+   * `baseRef` are ignored — the remote ref IS the base. Git arm:
+   * `git worktree add --track -b <branch> <path> <remoteRef>`. The explicit ref
+   * avoids the multi-remote DWIM `fatal: invalid reference` a bare `-b <branch>`
+   * would hit.
+   */
+  readonly remoteRef?: string | null;
+  /** `true` → create a new branch; `false` → check out an existing branch. */
+  readonly createBranch: boolean;
+}
+/**
+ * IPC-facing result of creating/locating a worktree. `created: false` means the
+ * branch already had a worktree and `path` points at it (open that window
+ * instead). The failure reasons map git's refusal modes to actionable copy.
+ * `branch-not-found` / `fetch-failed` arise only from the share-scoped
+ * `checkout` operation, whose branch resolution may `git fetch` from `origin`
+ * (branch gone upstream vs. a retryable network/timeout failure); the other
+ * failure reasons come from validation and `git worktree add`.
+ */
+type WorktreeCreateResult = {
+  readonly ok: true;
+  readonly path: string;
+  readonly created: boolean;
+} | {
+  readonly ok: false;
+  readonly reason: 'helper-not-found';
+  /**
+   * The command git tried to spawn and couldn't resolve (e.g. `git-lfs`),
+   * extracted by `detectMissingGitHelper`. Required on this arm so a
+   * producer can't emit the reason without naming the tool — the failure
+   * copy shows it verbatim so the user knows what to install.
+   */
+  readonly helper: string;
+  readonly message?: string;
+} | {
+  readonly ok: false;
+  readonly reason: 'fetch-failed';
+  readonly message?: string;
+  readonly helper?: never;
+  /**
+   * Set when the fetch failed for want of a usable credential rather than
+   * for a network/timeout reason, and re-authenticating could plausibly fix
+   * it (`isLoginFixableGitAuthError` — so not 403, scope-mismatch, or SSH
+   * key failures, which a sign-in doesn't repair).
+   *
+   * Its own arm rather than a field on the shared failure arm below: only
+   * `fetch-failed` reaches git's credential stage, so no other reason can
+   * structurally carry the flag. Optional and additive — a producer that
+   * omits it degrades to the generic connection-flavored copy, which is the
+   * pre-existing behavior.
+   */
+  readonly authFailed?: true;
+} | {
+  readonly ok: false;
+  readonly reason: 'invalid-branch' | 'branch-exists' | 'already-checked-out' | 'path-exists' | 'no-git' | 'branch-not-found'
+  /**
+   * The repository exists but has no commits, so no branch is a
+   * resolvable ref and `git worktree add` fails with
+   * `fatal: invalid reference: <base>`. Distinct from `no-git` (not a
+   * repository at all) and from `branch-not-found` (a repository with
+   * history where that particular branch is missing).
+   */
+  | 'empty-repo' | 'error';
+  readonly message?: string;
+  readonly helper?: never;
+};
+//#endregion
+//#region ../core/src/handoff/types.d.ts
+/** Failure classes reported by handoff telemetry and the desktop host bridge. */
+type HandoffFailureReason = 'not-installed' | 'scheme-blocked' | 'web-endpoint-error' | 'invalid-payload' | 'dispatch-error' | 'web-host-cursor-unsupported';
+/**
+ * Scope discriminator recorded on a handoff telemetry line. Present only on a
+ * selection-scoped dispatch; the file / folder / project scopes omit the
+ * field, so an absent `scope` reads as a non-selection handoff.
+ *
+ * Reused by the desktop telemetry channel and bridge rather than redeclared
+ * at each boundary.
+ */
+type HandoffScope = 'selection';
+//#endregion
+//#region ../core/src/handoff/terminal-launch.d.ts
+/**
+ * The agent CLIs the docked terminal can launch. Each starts an INTERACTIVE
+ * session that stays open with the composed prompt threaded in — NOT the
+ * non-interactive one-shot variants (`codex exec`, `cursor-agent -p`,
+ * `hermes -q`/`-z`) which run-and-exit before the user can continue.
+ *
+ * The prompt reaches the CLI three ways, per {@link TerminalCliInfo}:
+ *   - positional (`claude '<prompt>'`) — the default (no `promptFlag`);
+ *   - a flag (`opencode --prompt '<prompt>'`, `openclaw chat --message '<prompt>'`)
+ *     for CLIs whose positional isn't the prompt (`promptFlag`);
+ *   - post-launch PTY paste (`hermes`) for CLIs with NO starting-prompt argument
+ *     at all — the promptless `<bin>` is spawned and the prompt is bracketed-paste
+ *     injected once its TUI is ready (`startupInjection`).
+ */
+type TerminalCli = 'claude' | 'codex' | 'copilot' | 'cursor' | 'opencode' | 'pi' | 'antigravity' | 'openclaw' | 'hermes';
+//#endregion
 //#region ../core/src/i18n/locales.d.ts
 /**
  * The interface locales OpenKnowledge enumerates, ordered by total speakers.
@@ -10229,6 +10680,2151 @@ declare module 'mdast-util-math' {
   }
 } //# sourceMappingURL=mdast-augmentation.d.ts.map
 //#endregion
+//#region ../core/src/markdown/lint/types.d.ts
+declare const LINT_PLUGIN_IDS: readonly ["markdownlint", "frontmatter", "okf"];
+type LintPluginId = (typeof LINT_PLUGIN_IDS)[number];
+//#endregion
+//#region ../core/src/schemas/api/local-op.d.ts
+/**
+ * Response body for `POST /api/local-op/ok-init`, discriminated on `ok`.
+ *
+ * Both branches return HTTP 200; protocol-level errors (400 malformed
+ * body, 500 unexpected) use the standard RFC 9457 problem+json envelope.
+ *
+ * On success: `projectPath` is the realpath-collapsed path that was
+ * scaffolded (callers compare against their input to detect symlink
+ * resolution). The endpoint is idempotent — calling on an already-OK
+ * project returns `{ok: true}` without rewriting `config.yml`.
+ *
+ * On failure: `reason` discriminates the user-facing recovery path
+ * (not-a-git-worktree → re-pick a different folder; init-failed →
+ * surface the message and let the user inspect manually).
+ */
+declare const LocalOpOkInitResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
+  ok: ZodLiteral<true>;
+  projectPath: ZodString;
+}, $loose>, ZodObject<{
+  ok: ZodLiteral<false>;
+  reason: ZodEnum<{
+    "init-failed": "init-failed";
+    "not-a-git-worktree": "not-a-git-worktree";
+  }>;
+  message: ZodString;
+}, $loose>], "ok">;
+type LocalOpOkInitResponse = output<typeof LocalOpOkInitResponseSchema>;
+//#endregion
+//#region ../core/src/schemas/api/share.d.ts
+declare const BranchInfoResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
+  shareTargetExists: ZodBoolean;
+  dirtyConflicts: ZodObject<{
+    conflicts: ZodBoolean;
+    files: ZodArray<ZodString>;
+  }, $loose>;
+  branchIsLocal: ZodBoolean;
+  shareTargetOnOriginBranch: ZodOptional<ZodBoolean>;
+  detached: ZodLiteral<false>;
+  currentBranch: ZodNullable<ZodString>;
+  currentHeadSha: ZodNull;
+}, $loose>, ZodObject<{
+  shareTargetExists: ZodBoolean;
+  dirtyConflicts: ZodObject<{
+    conflicts: ZodBoolean;
+    files: ZodArray<ZodString>;
+  }, $loose>;
+  branchIsLocal: ZodBoolean;
+  shareTargetOnOriginBranch: ZodOptional<ZodBoolean>;
+  detached: ZodLiteral<true>;
+  currentBranch: ZodNull;
+  currentHeadSha: ZodString;
+}, $loose>], "detached">;
+type BranchInfoResponse = output<typeof BranchInfoResponseSchema>;
+/**
+ * Response body for `POST /api/git/checkout`, discriminated on `ok`.
+ *
+ * Both branches return HTTP 200; protocol-level errors (400 malformed
+ * body, 500 unexpected) use the standard RFC 9457 problem+json envelope
+ * via `errorResponse`. Logical failures carry the discriminated reason
+ * code so the dialog can map each to its own toast copy.
+ *
+ * On `dirty-conflict`, `files` is the same intersection-of-paths set
+ * `dirtyFilesOverlapWith` returns — sorted ascending, deduped. Omitted
+ * on all other failure variants and on success.
+ */
+declare const CheckoutResponseSchema: ZodDiscriminatedUnion<[ZodObject<{
+  ok: ZodLiteral<true>;
+}, $loose>, ZodObject<{
+  ok: ZodLiteral<false>;
+  reason: ZodEnum<{
+    "dirty-conflict": "dirty-conflict";
+    "branch-not-found": "branch-not-found";
+    "fetch-failed": "fetch-failed";
+    "checkout-failed": "checkout-failed";
+    "branch-in-other-worktree": "branch-in-other-worktree";
+    "ff-diverged": "ff-diverged";
+  }>;
+  files: ZodOptional<ZodArray<ZodString>>;
+  otherWorktreePath: ZodOptional<ZodString>;
+}, $loose>], "ok">;
+type CheckoutResponse = output<typeof CheckoutResponseSchema>;
+/**
+ * Response body for `POST /api/share/target-status`, discriminated on
+ * `verdict`. Only `renamed` carries `renamedTo` (the redirect target), so the
+ * illegal state "renamed with no destination" is unrepresentable.
+ *
+ * The whole union is value-tolerant: any parse failure — an unrecognized
+ * verdict from a newer server, or a malformed `renamed` missing `renamedTo` —
+ * collapses to `{ verdict: 'unknown' }`, so a skewed client degrades to today's
+ * guidance instead of throwing. Members are `.loose()` so the desktop proxy
+ * passes unknown additive fields through.
+ */
+declare const ShareTargetStatusResponseSchema: ZodCatch<ZodDiscriminatedUnion<[ZodObject<{
+  verdict: ZodLiteral<"on-origin">;
+}, $loose>, ZodObject<{
+  verdict: ZodLiteral<"renamed">;
+  renamedTo: ZodString;
+}, $loose>, ZodObject<{
+  verdict: ZodLiteral<"deleted">;
+}, $loose>, ZodObject<{
+  verdict: ZodLiteral<"never-on-branch">;
+}, $loose>, ZodObject<{
+  verdict: ZodLiteral<"changed-locally">;
+}, $loose>, ZodObject<{
+  verdict: ZodLiteral<"unknown">;
+}, $loose>], "verdict">>;
+type ShareTargetStatusResponse = output<typeof ShareTargetStatusResponseSchema>;
+//#endregion
+//#region ../core/src/sharing/receive-flow.d.ts
+/**
+ * Recent-projects row. `missing` is set at read time by main (folder was
+ * absent when the list was assembled). `gitRemoteUrl` is the canonical
+ * `https://github.com/<owner>/<repo>.git` form when available (open-time
+ * backfill from `.git/config`).
+ */
+interface RecentProjectEntry {
+  path: string;
+  name: string;
+  lastOpenedAt: string;
+  missing?: boolean;
+  gitRemoteUrl?: string;
+  /**
+   * Git-worktree relationship, computed at list-time (not persisted) so the
+   * project switcher can nest linked worktrees under their main project.
+   * Absent for non-git projects. `gitCommonDir` is the repo identity shared by
+   * all worktrees; `mainRoot` is the repo's main worktree root; `branch` is the
+   * checked-out branch (null on detached HEAD).
+   */
+  gitCommonDir?: string;
+  mainRoot?: string;
+  isLinkedWorktree?: boolean;
+  branch?: string | null;
+}
+//#endregion
+//#region ../core/src/skills-catalog/skill-cost.d.ts
+/**
+ * A skill's context cost in estimated tokens, split by when the cost is paid.
+ * There is deliberately no summed total: a single figure misranks skills whose
+ * weight sits in different tiers (a lean index in front of a heavy body vs. the
+ * reverse), so every surface renders the three tiers or a documented subset.
+ *
+ * The zod schema is the single source both the estimator's return type and the
+ * skills-list wire field derive from, so the shape cannot drift between the
+ * producer and the transport.
+ */
+declare const SkillCostTiersSchema: ZodObject<{
+  alwaysOn: ZodNumber;
+  onTrigger: ZodNumber;
+  onDemand: ZodNumber;
+}, $strict>;
+type SkillCostTiers = output<typeof SkillCostTiersSchema>;
+//#endregion
+//#region ../core/src/terminal-layout.d.ts
+declare const TERMINAL_PLACEMENTS: readonly ["bottom", "right"];
+type TerminalPlacement = (typeof TERMINAL_PLACEMENTS)[number];
+//#endregion
+//#region ../core/src/desktop-bridge.d.ts
+interface OkTerminalRestartTab {
+  ordinal: number;
+  customLabel: string | null;
+}
+interface OkTerminalRestartSnapshot {
+  tabs: OkTerminalRestartTab[];
+  activeOrdinal: number | null;
+}
+interface OkTerminalDockState {
+  terminalVisible: boolean;
+  agentPanelVisible: boolean;
+  terminal?: {
+    order: string[];
+    activeKey: string | null;
+  };
+  terminalSnapshot?: OkTerminalRestartSnapshot;
+  agents?: {
+    order: string[];
+    activeKey: string | null;
+  };
+}
+/**
+ * A conversation or comments action started in a popped-out note window and
+ * handed back to the owning project window. The note renderer composes the
+ * same bounded prompt it would use locally; main only resolves/focuses the
+ * project window and forwards this typed intent.
+ */
+type OkNoteWindowMainAction = {
+  readonly kind: 'active-input';
+  readonly text: string;
+  readonly newTab: boolean;
+  readonly submit: boolean;
+  readonly target?: 'agents';
+} | {
+  readonly kind: 'agent-thread';
+  readonly agentSource: 'registry' | 'custom';
+  readonly agentId: string;
+  readonly prompt: string | null;
+  readonly docName: string | null;
+  readonly titleHint: string | null;
+} | {
+  readonly kind: 'terminal-launch';
+  readonly prompt: string;
+  readonly cli: TerminalCli;
+  readonly stage: boolean;
+} | {
+  readonly kind: 'reveal-comments';
+  readonly docName: string;
+  readonly scope: 'doc' | 'queue';
+};
+type OkNoteWindowMainActionResult = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly reason: 'invalid-action' | 'not-note-window' | 'project-not-open';
+};
+type OkTerminalDockStateUpdate = {
+  surface: 'terminal';
+  order: string[];
+  activeKey: string | null;
+  terminalSnapshot: OkTerminalRestartSnapshot;
+} | {
+  surface: 'agents';
+  order: string[];
+  activeKey: string | null;
+};
+type OkTerminalDockStateWriteResult = {
+  ok: true;
+} | {
+  ok: false;
+  reason: 'invalid-request' | 'no-window-context' | 'persist-failed' | 'ipc-unavailable';
+};
+/** Render mode picked by the main process when creating a BrowserWindow. */
+type OkDesktopMode = 'editor' | 'navigator' | 'terminal' | 'note';
+/**
+ * Config values injected at preload-exposure time. A frozen snapshot, not a
+ * getter — mid-session project switches fire through `onProjectSwitched`
+ * instead. Required fields are present before the first renderer render
+ * because the main process awaits the utility's `ready` message before
+ * creating the BrowserWindow.
+ */
+interface OkDesktopConfig {
+  /** WebSocket URL for the HocuspocusProvider (ws://localhost:<port>/collab). */
+  readonly collabUrl: string;
+  /** Origin for HTTP /api/* fetches (http://localhost:<port>). */
+  readonly apiOrigin: string;
+  /** Realpath of the project's content directory. */
+  readonly projectPath: string;
+  /** Display name for the project (usually basename of projectPath). */
+  readonly projectName: string;
+  /** Render mode — `navigator` renders the Project Navigator, `editor` renders the doc editor, `terminal` renders the standalone terminal window, `note` renders a single popped-out document full-window. */
+  readonly mode: OkDesktopMode;
+  readonly e2eSmoke: boolean;
+  readonly singleFile: boolean;
+  readonly initialDoc: string | null;
+  readonly freshlyCreated: boolean;
+  readonly startupTraceparent?: string;
+  readonly ptyAvailable: boolean;
+  /**
+   * The saved interface-language choice, unresolved, as main read it off disk
+   * while starting this window.
+   *
+   * Windows that mount a `ConfigProvider` get the preference from config and
+   * ignore this. The launcher has no project and therefore no config document,
+   * so without a value here it renders the bootstrap catalog under a menu bar
+   * main has already translated — main resolves the preference before any
+   * window exists, which is the whole reason the menus are right.
+   *
+   * Unresolved on purpose: `'system'` has to arrive as `'system'` so the
+   * renderer re-resolves it against the browser's current list rather than
+   * freezing whatever the OS said when the window opened.
+   */
+  readonly languagePreference?: LanguagePreference;
+}
+/**
+ * Menu-action IDs fired by main → renderer via `ok:menu-action` after a user
+ * selects a menu bar item. The renderer dispatches the action into the editor
+ * store. Keep this union flat and strongly typed — a single `kind` field
+ * discriminates without payload.
+ */
+type OkMenuAction = 'new-doc' | 'new-folder' | 'new-project' | 'rename' | 'delete' | 'close-active-tab-or-window' | 'toggle-sidebar' | 'toggle-source' | 'save-version' | 'version-history' | 'focus-search' | 'focus-command-palette' | 'navigate-back' | 'navigate-forward' | 'new-from-template' | 'duplicate' | 'move-to-trash' | 'reveal-in-finder' | 'send-to-ai' | 'copy-full-path' | 'copy-relative-path' | 'toggle-show-hidden-files' | 'toggle-show-ok-folders' | 'toggle-show-only-markdown-files' | 'toggle-show-skills-section' | 'expand-all-tree' | 'collapse-all-tree' | 'toggle-doc-panel' | 'toggle-terminal' | 'move-terminal' | 'toggle-agent-panel' | 'new-terminal' | 'kill-terminal' | 'new-worktree' | 'switch-worktree' | 'report-bug' | 'send-feedback';
+/**
+ * Unsubscribe closure returned from `onProjectSwitched` / `onMenuAction`.
+ * Calling it removes the listener. Per-electron#33328, the bridge's
+ * preload-side wrapper is what actually tracks the listener reference so
+ * callers must use this returned closure rather than trying to remove by
+ * reference from their own code.
+ */
+type OkUnsubscribe = () => void;
+interface PersistedEditorPane {
+  id: string;
+  openTabs: string[];
+  pinnedTabIds: string[];
+  activeTabId: string | null;
+  size: number;
+}
+interface ProjectSessionState {
+  activeTabByMode: {
+    files: string | null;
+    skills: string | null;
+  };
+  updatedAt: string | null;
+  panes: PersistedEditorPane[];
+  focusedPaneId: string;
+}
+/**
+ * Discriminator for the Navigator-side surface that initiated a project-open.
+ * Matches the desktop runtime `EntryPoint` discriminator.
+ */
+type OkProjectEntryPoint = 'create-new' | 'create-new-nested-redirect' | 'pick-existing' | 'recents' | 'deep-link' | 'drag-drop' | 'share-receive' | 'worktree';
+/**
+ * Payload accepted by `bridge.project.open(...)`. `target` stays in the
+ * contract for forward-compat even though `'new-window'` is the only value
+ * today (no switch-in-place). `entryPoint` tags the originating surface so
+ * the consent-dialog gate can branch on user intent.
+ */
+interface OkProjectOpenRequest {
+  path: string;
+  target: 'new-window';
+  entryPoint: OkProjectEntryPoint;
+  /**
+   * Optional kind-discriminated target to deep-link into after the project
+   * window mounts. Used by share-receive: Q1 hits and Q2/Q3 success both
+   * pass the share's target (a `doc` path or a `folder` path) so the editor
+   * opens it directly. Threaded through to `wm.createProjectWindow`'s
+   * `pendingDeepLinkTarget` (cold spawn → `dom-ready` deep-link IPC) and to
+   * `sendDeepLink` for the warm-focus path. Mirrors the existing
+   * `openknowledge://open?project=&doc=` flow.
+   */
+  pendingDeepLinkTarget?: {
+    kind: 'doc' | 'folder'; /** Content-relative renderer navigation path. */
+    path: string; /** Repository-relative path used only by receive-side Git/filesystem probes. */
+    repositoryPath?: string; /** Present only for v2; strips the repository prefix from rename results. */
+    contentRootDepth?: number;
+  };
+  /**
+   * Optional share branch riding alongside `pendingDeepLinkTarget`. See
+   * canonical bridge contract below.
+   */
+  pendingBranch?: string | null;
+  /**
+   * Optional branch-switch payload for the share-receive "I already have it
+   * locally" path. When the located clone
+   * is on a different branch than the share, main delivers the
+   * `project-branch-switch` surface instead of a plain deep-link open.
+   */
+  pendingShareBranchSwitch?: {
+    share: OkSharePayloadFields;
+    projectPath: string;
+    currentBranch: string | null;
+  };
+}
+/**
+ * Outcome of `bridge.project.checkTargetExists({projectPath, kind, path})`.
+ * Alias used by existing desktop consumers as `CheckTargetExistsResult`.
+ *
+ * Used by the main-side target-existence gate AFTER the branch comparison
+ * passes — answers "does the share's target actually exist on the receiver's
+ * currently-checked-out branch?" The `'unreadable'` sentinel collapses
+ * the input-rejection + non-ENOENT I/O paths into a single graceful-fail
+ * the caller treats as "silent dispatch is safe."
+ */
+type OkCheckTargetExistsResult = 'exists' | 'missing' | 'unreadable';
+/**
+ * Outcome of `bridge.project.readHeadBranch(projectPath)`.
+ *
+ * All-null + `detached: false` is the "couldn't determine" sentinel returned
+ * on every failure mode (missing `.git`, malformed HEAD, I/O error, traversal
+ * attempt). Used by the Project Navigator's recent-projects list.
+ */
+interface OkHeadBranchInfo {
+  readonly currentBranch: string | null;
+  readonly headSha: string | null;
+  readonly detached: boolean;
+}
+/**
+ * Payload delivered to `onUpdateDownloaded` subscribers. Fires after
+ * electron-updater has completed the ZIP download and is waiting for
+ * install-on-quit (or an imperative `autoUpdater.quitAndInstall()` via
+ * Toast A's "Relaunch now" action).
+ */
+interface OkUpdateDownloadedInfo {
+  readonly version: string;
+}
+/**
+ * Payload delivered to `onUpdateRelaunching` subscribers. Fires when one
+ * window's "Relaunch now" click commits in main (`ok:update:relaunch-now`
+ * passed its `versionPendingInstall` gate). Every window swaps its
+ * `update-downloaded` card to the in-progress "Relaunching…" state.
+ */
+interface OkUpdateRelaunchingInfo {
+  readonly version: string;
+}
+/**
+ * Payload delivered to `onUpdateRelaunchFailed` subscribers. Fires when a
+ * committed relaunch fails after the fact — the updater's `error` event
+ * landed while the relaunch was in flight, the no-quit watchdog elapsed, or
+ * `quitAndInstall()` threw. Main re-arms the banner separately via a
+ * re-broadcast `ok:update:downloaded`; this carries the failure detail.
+ */
+interface OkUpdateRelaunchFailedInfo {
+  readonly version: string;
+  readonly message?: string;
+  readonly downloadUrl?: string;
+}
+/**
+ * Payload delivered to `onWhatsNew` subscribers. Fires once per version
+ * transition on first launch post-update (main compared `app.getVersion()`
+ * to `AppState.lastSeenVersion`). `releaseUrl` is the GitHub Releases page
+ * for the new version — renderer opens it via `bridge.shell.openExternal`.
+ */
+interface OkWhatsNewInfo {
+  readonly version: string;
+  readonly releaseUrl: string;
+}
+/**
+ * Payload delivered to `onUpdateStuckHint` subscribers. Fires at most once
+ * per installation after 7 consecutive calendar days of failed update
+ * checks. `downloadUrl` is the manual-download page (inkeep.com's
+ * OpenKnowledge download CTA); renderer opens it via
+ * `bridge.shell.openExternal`.
+ */
+interface OkUpdateStuckHintInfo {
+  readonly downloadUrl: string;
+}
+/**
+ * Renderer-facing payload for `ok:share-received`. Carried by the main-
+ * process share-flow handler in `url-scheme.ts` after `parseShareUrl`
+ * dispatches on the universal-link / custom-scheme input shapes.
+ *
+ *   - `kind: 'project-branch-switch'` — editor-shell branch-switch surface
+ *   - `kind: 'launcher-consent'` / `launcher-miss` — Navigator surfaces
+ *   - `kind: 'unsupported-version'` — sonner toast "Update OpenKnowledge"
+ *   - `kind: 'invalid'` — sonner toast "Invalid share URL"
+ *
+ * Source (universal-link vs custom-scheme) is NOT propagated — main-process
+ * diagnostic logging only.
+ */
+/** Kind-discriminated receiver target carried by `OkSharePayloadFields`. */
+type ShareTarget = {
+  readonly kind: 'doc';
+  readonly docPath: string;
+} | {
+  readonly kind: 'folder';
+  readonly folderPath: string;
+};
+/** Parsed project-share fields carried across the desktop host bridge. */
+interface OkSharePayloadFields {
+  /** GitHub host of the shared repo: `github.com` or a GHES hostname. */
+  readonly host: string;
+  readonly owner: string;
+  readonly repo: string;
+  readonly branch: string;
+  readonly sharedUrl: string;
+  /** URL-derived repository coordinate. Never inferred from receiver config. */
+  readonly repositoryTarget: ShareTarget;
+  /** `null` for historical v1; positive decoded prefix depth for v2. */
+  readonly contentRootDepth: number | null;
+  readonly target: ShareTarget;
+}
+/** Renderer-facing payload for a received project share. */
+type OkShareReceivedPayload = {
+  readonly kind: 'unsupported-version';
+} | {
+  readonly kind: 'invalid';
+} | {
+  readonly kind: 'project-branch-switch';
+  readonly share: OkSharePayloadFields;
+  readonly projectPath: string;
+  readonly currentBranch: string | null;
+} | {
+  readonly kind: 'launcher-consent';
+  readonly share: OkSharePayloadFields;
+  readonly candidatePath: string;
+  /**
+   * Name of the Recents project whose `listGitWorktrees` anchor surfaced
+   * `candidatePath`, when the candidate came from worktree-enum off an
+   * existing OK project. `null` when the candidate was surfaced from
+   * a Recents path that itself matched the share. Drives the
+   * "(a worktree of <name>)" caption in the Navigator consent dialog.
+   */
+  readonly parentProjectName: string | null;
+} | {
+  readonly kind: 'launcher-miss';
+  readonly share: OkSharePayloadFields;
+};
+/**
+ * Renderer-facing representation of `ShareFolderValidationResult` from
+ * `@inkeep/open-knowledge`'s `validateLocalFolderForShare`. Carried
+ * by the `share.validateLocalFolder` IPC.
+ */
+type ShareFolderValidationResult$1 = {
+  readonly kind: 'ok';
+  readonly gitRemoteUrl: string;
+} | {
+  readonly kind: 'not-git';
+} | {
+  readonly kind: 'no-origin';
+} | {
+  readonly kind: 'wrong-repo';
+  readonly actualOwner: string;
+  readonly actualRepo: string;
+} | {
+  readonly kind: 'wrong-host';
+  readonly actualHost: string;
+} | {
+  readonly kind: 'non-github';
+} | {
+  readonly kind: 'symlink-escape';
+};
+/**
+ * Auto-update channel — derived in desktop's main from the running build's
+ * version string. `'beta'` for a prerelease build, `'latest'` for a stable
+ * one. Not a runtime preference. Mirrors `UpdateChannel` in desktop's
+ * `state-store.ts`.
+ */
+type OkUpdateChannel = 'latest' | 'beta';
+/**
+ * User-intent theme value. Mirrors Electron's `nativeTheme.themeSource`
+ * union. Carried verbatim through the `ok:theme:set-source` IPC channel —
+ * never resolved to a concrete light/dark value at the renderer call site
+ * (the `'system'` value IS the lever that delegates appearance tracking to
+ * macOS). The desktop and app compatibility paths re-export this declaration.
+ */
+type OkThemeSource = 'system' | 'light' | 'dark';
+/** Colors handed to Electron for OS-drawn window chrome. */
+interface OkChromeColors {
+  /** Active theme's sidebar surface color. */
+  bg: string;
+  /** Active theme's sidebar foreground color. */
+  symbol: string;
+}
+/**
+ * Snapshot returned by `state.query()` — newly-opened windows query on
+ * mount to render the correct BETA badge / About-panel label (channel is
+ * build-derived) and to route the refuse-downgrade UX when a future-build
+ * state was rolled back.
+ */
+interface OkStateSnapshot {
+  readonly channel: OkUpdateChannel;
+  readonly schemaIncompatibility: {
+    readonly currentBuild: string;
+    readonly persistedSchemaVersion: number;
+    readonly maxSupported: number;
+  } | null;
+}
+/**
+ * Editor IDs surfaced through the first-launch MCP consent bridge.
+ * Aliased to the canonical `EditorId` from `constants/editors.ts` — single
+ * source of truth for the literal union.
+ */
+type OkMcpWiringEditorId = EditorId$1;
+/**
+ * Payload delivered to `mcpWiring.onShow` subscribers on first-launch MCP
+ * consent. Every editor in `ALL_EDITOR_IDS` appears, but only `detected: true`
+ * ones are in `<McpConsentDialog>`'s write set — the rest have no config to
+ * wire and are not shown. `willReplace: true` signals an existing OK-managed
+ * entry the setup would overwrite, which the dialog surfaces next to its
+ * checkbox so long-time CLI users aren't surprised to find their pre-existing
+ * entry stomped. `pathInstall` drives the dialog's shell-PATH toggle row:
+ * `shellDetected: false` hides the row; `alreadyInstalled: true` renders it
+ * informational; `rcFilesToTouch` names the tildified shell files a grant
+ * would edit.
+ */
+interface OkMcpWiringShowPayload {
+  readonly detectedEditors: readonly {
+    readonly id: OkMcpWiringEditorId;
+    readonly label: string;
+    readonly detected: boolean;
+    readonly willReplace: boolean; /** Display-form user-global config path, or null when unavailable. */
+    readonly configPath: string | null; /** Locator for OpenKnowledge's entry within the editor config. */
+    readonly entryLocator: string;
+  }[];
+  readonly pathInstall: {
+    readonly shellDetected: boolean;
+    readonly rcFilesToTouch: readonly string[];
+    readonly alreadyInstalled: boolean;
+  };
+  /** The user-global skill bundles onboarding sets up alongside the MCP wiring.
+   *  Empty ⇒ no skill decision solicited. `paths` lists every destination the
+   *  install writes to, computed from the installer's own iteration set and
+   *  gates, so the dialog's disclosure can never advertise a copy that will not
+   *  be made. */
+  readonly globalSkills: readonly {
+    readonly id: string;
+    readonly name: string;
+    readonly paths: readonly string[];
+  }[];
+}
+/**
+ * Confirm payload for `mcpWiring.confirm`. `pathInstall` is the PATH
+ * toggle, tri-state: `true` → append the managed rc block (consent
+ * granted); `false` → record declined, touch no rc file; absent → no PATH
+ * decision was solicited (row hidden or informational).
+ *
+ * `skills` — bundle ids the user left checked. An ARRAY (even empty) ⇒ a
+ * decision was made, and every offered bundle not in the list is recorded
+ * declined (and removed if already installed). Absent ⇒ no decision was made:
+ * the skills leg is skipped, so nothing is written and nothing installed is
+ * torn down. Onboarding sends the absent form when the user declines setup,
+ * because declining must never uninstall an existing bundle.
+ */
+interface OkMcpWiringConfirmRequest {
+  readonly editorIds: readonly OkMcpWiringEditorId[];
+  readonly pathInstall?: boolean;
+  readonly skills?: readonly string[];
+}
+/**
+ * Result shape for `mcpWiring.confirm` / `skip`. `ok:false` surfaces only
+ * when `writeUserMcpConfigs` throws — per-editor failures still resolve
+ * `ok:true` and are surfaced to operator logs via structured
+ * `mcp-wiring-write-failed` events (deferred-marker semantics).
+ */
+type OkMcpWiringResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Per-editor MCP state for Settings → AI tools. `installed` rows uncheck to
+ * remove; `not-installed` rows check to install; `foreign` is an entry under
+ * OK's server name that isn't recognizably OK's own (uninstall refuses,
+ * install overwrites); `unmanageable` is a config OK can't safely edit.
+ */
+type OkIntegrationsEditorState = 'installed' | 'not-installed' | 'foreign' | 'unmanageable';
+/** Component inventory for Settings → AI tools. `available: false` renders
+ *  the section read-only (install actors gated off for this process). `path.
+ *  installed` reflects the managed rc block actually being on disk. */
+interface OkIntegrationsStatus {
+  readonly available: boolean;
+  readonly editors: readonly {
+    readonly id: OkMcpWiringEditorId;
+    readonly label: string;
+    readonly detected: boolean;
+    readonly state: OkIntegrationsEditorState;
+    readonly configPath: string | null;
+    readonly entryLocator: string;
+  }[];
+  readonly path: {
+    readonly shellDetected: boolean;
+    readonly rcFilesToTouch: readonly string[];
+    readonly installed: boolean;
+  };
+  readonly skills: readonly {
+    readonly id: string;
+    readonly name: string;
+    /** The skill's own frontmatter description; empty when the bundle is
+     *  unreadable. Replaces the hand-written per-id subtext on the row. */
+    readonly description: string;
+    readonly installed: boolean;
+    readonly paths: readonly string[];
+    /** Three-tier context cost from the shared estimator. Absent when the
+     *  bundle could not be parsed (broken build) — the row hides the cost. */
+    readonly size?: SkillCostTiers; /** On-disk source directory of the built-in bundle (its SKILL.md + files). */
+    readonly sourceDir: string;
+    /** Every place this skill would install: static agent hosts present on disk
+     *  plus declared custom roots. For a custom root `editor === skillsRoot`. */
+    readonly resolvedHosts: readonly {
+      readonly editor: string;
+      readonly skillsRoot: string;
+      readonly custom: boolean;
+    }[];
+  }[];
+  /**
+   * Every editor whose host root already exists on this machine — a SUPERSET
+   * of the ids in `editors[]`, which is filtered to targets with a user-global
+   * MCP surface. The Create-new-project dialog seeds its editor checkboxes
+   * from this so a user who never opens "Advanced settings" still gets MCP
+   * config + the project skill for the tools they actually have, and none for
+   * the ones they don't.
+   */
+  readonly detectedEditorIds: readonly OkMcpWiringEditorId[];
+}
+/** One toggle for `integrations.setComponent`. */
+interface OkIntegrationsSetRequest {
+  readonly component: {
+    readonly kind: 'editor';
+    readonly id: OkMcpWiringEditorId;
+  } | {
+    readonly kind: 'path';
+  } | {
+    readonly kind: 'skill';
+    readonly id: string;
+  };
+  readonly enabled: boolean;
+}
+/** Set-component result — both arms carry a fresh status snapshot so the
+ *  renderer re-renders truthfully after failed/refused toggles too. */
+type OkIntegrationsSetResult = {
+  readonly ok: true;
+  readonly status: OkIntegrationsStatus;
+} | {
+  readonly ok: false;
+  readonly error: string;
+  readonly status: OkIntegrationsStatus;
+};
+/** Post-install manual step a project MCP config needs before OK's tools
+ *  connect: `approve-once` (Claude Code), `enable-manually` (Cursor, silently
+ *  disabled until toggled), `auto-connect` (Codex on a trusted project),
+ *  `none`. */
+type OkProjectIntegrationsFollowUp = 'approve-once' | 'enable-manually' | 'auto-connect' | 'none';
+/** Component inventory for Settings → This project → AI tools (per-editor
+ *  PROJECT MCP config files + the single project runtime skill), scoped to the
+ *  project the requesting window has open. `hasProject: false` → empty state;
+ *  `available: false` → read-only. */
+interface OkProjectIntegrationsStatus {
+  readonly available: boolean;
+  readonly hasProject: boolean;
+  readonly projectDir: string | null;
+  readonly editors: readonly {
+    readonly id: OkMcpWiringEditorId;
+    readonly label: string;
+    readonly state: OkIntegrationsEditorState;
+    readonly configPath: string;
+    readonly entryLocator: string;
+    readonly followUp: OkProjectIntegrationsFollowUp;
+  }[];
+  readonly skill: {
+    readonly installed: boolean;
+    readonly paths: readonly string[];
+    /** The skill's own frontmatter description, so the row states what the
+     *  bundle says rather than a hand-written subtext that can drift from it. */
+    readonly description: string;
+    /** Editor ids this project's skill fans out to — the reach cluster's input.
+     *  Project-scoped, so these are the editors with a project skill root here,
+     *  not the user-global host set. */
+    readonly hosts: readonly string[];
+    /** Three-tier context cost of the bundled project skill. Absent when the
+     *  bundle cannot be read. */
+    readonly size?: SkillCostTiers; /** On-disk source of the bundled skill, so the row can open its preview. */
+    readonly sourceDir?: string;
+  } | null;
+}
+/** One toggle for `projectIntegrations.setComponent`. The skill is a single
+ *  row (no id) — it fans out across every capable editor. */
+interface OkProjectIntegrationsSetRequest {
+  readonly component: {
+    readonly kind: 'editor';
+    readonly id: OkMcpWiringEditorId;
+  } | {
+    readonly kind: 'skill';
+  };
+  readonly enabled: boolean;
+}
+type OkProjectIntegrationsSetResult = {
+  readonly ok: true;
+  readonly status: OkProjectIntegrationsStatus;
+} | {
+  readonly ok: false;
+  readonly error: string;
+  readonly status: OkProjectIntegrationsStatus;
+};
+/**
+ * Per-project consent dialog — renderer-facing payload + result shapes.
+ */
+type OkOnboardingWarningKind = 'root' | 'home' | 'home-documents' | 'home-desktop' | 'home-downloads' | 'volumes-mount' | 'drive-root';
+type OkOnboardingGitState = 'present' | 'absent' | 'shell-only';
+interface OkOnboardingShowPayload {
+  readonly pickedPath: string;
+  readonly projectDir: string;
+  readonly defaultContentDir: string;
+  readonly gitState: OkOnboardingGitState;
+  readonly gitRootPromoted: boolean;
+  readonly warnings: readonly {
+    readonly kind: OkOnboardingWarningKind;
+  }[];
+  readonly editorOptions: readonly {
+    readonly id: OkMcpWiringEditorId;
+    readonly label: string;
+    readonly hasProjectConfig: boolean;
+    /** Optional for back-compat; absent reads as `true`. `false` = the editor
+     *  has no user-global config surface (Pi — project-scope only). */
+    readonly hasUserConfig?: boolean;
+  }[];
+}
+interface OkOnboardingConfirmRequest {
+  readonly initGit: boolean;
+  readonly contentDir: string;
+  readonly additionalIgnores: string;
+  readonly editorIds: readonly OkMcpWiringEditorId[];
+  readonly sharing: 'shared' | 'local-only';
+}
+type OkOnboardingResult = {
+  ok: true;
+} | {
+  ok: false;
+  error: string;
+};
+interface OkOnboardingProbeContentRequest {
+  readonly contentDir: string;
+}
+type OkOnboardingProbeContentResult = {
+  readonly ok: true;
+  readonly count: number;
+  readonly sample: readonly string[];
+  readonly truncated: boolean;
+} | {
+  readonly ok: false;
+  readonly error: string;
+};
+/**
+ * Result shape for `bridge.debug?.keyringSmoke()` — mirrors
+ * `KeyringSmokeResult` in `packages/desktop/src/utility/keyring-smoke.ts`
+ * (identical field set). Duplicated here (not imported) because core has no
+ * dep on desktop. The desktop utility remains checked against this canonical
+ * field set by the desktop architecture test.
+ */
+interface OkKeyringSmokeResult {
+  ok: boolean;
+  backend?: 'keyring' | 'file';
+  error?: string;
+  durationMs?: number;
+  timestamp: string;
+}
+/**
+ * Seed scaffolder shapes duplicated structurally (same rationale as
+ * `OkKeyringSmokeResult` above — avoids pulling the server package into
+ * core's compilation tree). Structural shape tracks
+ * `@inkeep/open-knowledge-server`'s `ScaffoldPlan` / `ApplyResult` /
+ * `ApplyError` / `FileEntry` / `SkipEntry`.
+ *
+ * Folder defaults moved out of `config.yml` `folders:` and into nested
+ * `<folder>/.ok/frontmatter.yml` files written via the standard file-entry
+ * path. The previous `OkFolderRule` / `OkScaffoldConfigEdit` mirror types
+ * + the `configEdits` field on `OkScaffoldPlan` were removed alongside.
+ */
+interface OkScaffoldFileEntry {
+  path: string;
+  kind: 'folder' | 'file';
+  contentPreview?: string;
+}
+interface OkScaffoldSkipEntry {
+  path: string;
+  reason: 'already-exists' | 'user-content' | 'glob-collision';
+}
+interface OkScaffoldPlan {
+  created: OkScaffoldFileEntry[];
+  skipped: OkScaffoldSkipEntry[];
+  warnings: string[];
+  /** Project-local skills shipped by the pack. `pending` means apply would
+   * author or refresh the skill source. `conflict` means a user-owned skill
+   * holds the name; apply will neither install nor clobber it. */
+  packSkills?: {
+    name: string;
+    pending: boolean;
+    conflict?: boolean;
+  }[];
+  /**
+   * Lint plugins the pack requires. `pending` means apply would turn one on.
+   *
+   * `id` is the plugin union rather than a bare `string`: this interface is
+   * hand-mirrored from the server's `ScaffoldPlan`, and the preload passes one
+   * where the other is expected — so a widened field here does not read as
+   * "more permissive", it fails to assign.
+   */
+  requiredPlugins?: {
+    id: LintPluginId;
+    pending: boolean;
+  }[];
+}
+interface OkScaffoldApplyError {
+  path: string;
+  error: string;
+}
+interface OkScaffoldApplyResult {
+  applied: number;
+  errors: OkScaffoldApplyError[];
+  durationMs: number;
+  /** Editor display-names that received the pack's project skill (e.g. "Claude Code"). */
+  packSkillsInstalled: string[];
+  /** Required plugins this apply actually turned on; empty when all were already enabled. */
+  pluginsEnabled: LintPluginId[];
+  /** Pack skills skipped because a user-owned same-named skill holds the name. */
+  packSkillConflicts: {
+    name: string;
+    hosts?: string[];
+  }[];
+}
+interface OkSeedError {
+  kind: 'no-project' | 'prerequisite-missing' | 'invalid-root' | 'internal';
+  message: string;
+}
+/**
+ * Pack-id wire shape — accepted strings; coerced server-side via `coercePackId`.
+ *
+ * This bridge leaf is the renderer contract's single declaration point.
+ */
+type OkPackId = 'knowledge-base' | 'software-lifecycle' | 'codebase-wiki' | 'plain-notes' | 'worldbuilding' | 'writing-pipeline' | 'entity-vault' | 'okf';
+interface OkSeedPlanOptions {
+  rootDir?: string;
+  packId?: OkPackId;
+  /**
+   * Preview a pack for a project that does not exist yet. The create-new
+   * dialog runs on the Navigator window, which has no project bound, so the
+   * normal `resolveProjectRoot` path answers `no-project`. Main plans against
+   * a throwaway directory instead, so every entry reads as `created`.
+   *
+   * `skillsInstallable` is the part only the caller knows: whether the project
+   * about to be created has an editor selected, and so whether the pack's
+   * skills will actually install once it exists.
+   */
+  preview?: {
+    skillsInstallable: boolean;
+  };
+}
+interface OkSeedApplyOptions {
+  packId?: OkPackId;
+}
+interface OkSeedPackFolderInfo {
+  path: string;
+  summary: string;
+}
+/**
+ * User-visible entry counts surfaced on each pack picker card as
+ * "N files · N folders".
+ */
+interface OkSeedPackEntryCounts {
+  files: number;
+  folders: number;
+}
+interface OkSeedPackInfo {
+  id: OkPackId;
+  name: string;
+  description: string;
+  defaultSubfolder?: string;
+  folders: OkSeedPackFolderInfo[];
+  entryCounts: OkSeedPackEntryCounts;
+}
+/** Pure-fs upward-walk result types mirrored from `@inkeep/open-knowledge-server`'s
+ *  `fs/` module. Structurally duplicated for the same reason as the seed shapes
+ *  above (core has no dep on server). */
+interface OkFindEnclosingProjectRootResult {
+  readonly rootPath: string;
+  readonly distance: number;
+}
+interface OkFindEnclosingGitRootResult {
+  readonly gitRoot: string;
+  readonly distance: number;
+}
+type OkSeedPlanResult = {
+  ok: true;
+  plan: OkScaffoldPlan;
+} | {
+  ok: false;
+  error: OkSeedError;
+};
+type OkSeedApplyResult = {
+  ok: true;
+  result: OkScaffoldApplyResult;
+} | {
+  ok: false;
+  error: OkSeedError;
+};
+type OkSeedListPacksResult = {
+  ok: true;
+  packs: OkSeedPackInfo[];
+} | {
+  ok: false;
+  error: {
+    kind: 'internal';
+    message: string;
+  };
+};
+/**
+ * Pre-project local-op event shapes — auth + clone flows surfaced to the
+ * Navigator window via IPC because it has no backing API server.
+ */
+type OkLocalOpAuthEvent = {
+  type: 'verification';
+  user_code: string;
+  verification_uri: string;
+  expires_in: number;
+} | {
+  type: 'complete';
+  host: string;
+  login: string;
+  name?: string;
+  email?: string;
+  avatarUrl?: string;
+} | {
+  type: 'error';
+  message: string;
+};
+type OkLocalOpCloneEvent = {
+  type: 'progress';
+  phase: string;
+  pct: number;
+} | {
+  type: 'complete';
+  dir: string;
+} | {
+  type: 'branch-fallback';
+  branch: string;
+} | {
+  type: 'error';
+  message: string;
+};
+interface OkLocalOpStream<E> {
+  readonly events: AsyncIterable<E>;
+  cancel(): void;
+}
+type OkLocalOpAuthStatusResponse = {
+  authenticated: true;
+  host: string;
+  login: string;
+  tier?: 'A' | 'B' | 'C';
+  name?: string;
+  email?: string;
+  ghAvailable?: boolean;
+} | {
+  authenticated: false;
+  host: string;
+  error?: string;
+  ghAvailable?: boolean;
+};
+interface OkLocalOpRepoEntry {
+  full_name: string;
+  clone_url: string;
+  private: boolean;
+}
+type OkLocalOpAuthReposResponse = {
+  ok: true;
+  host: string;
+  repos: OkLocalOpRepoEntry[];
+} | {
+  ok: false;
+  error: string;
+};
+/**
+ * Renderer → main snapshot of the editor area's active target.
+ * Discriminated-union shape so TypeScript narrows `identifier` per `kind`.
+ * Drives the macOS File menu's state-aware enable/disable for items like
+ * Rename / Move to Trash / Open with AI.
+ */
+type OkEditorActiveTargetSnapshot = {
+  readonly kind: 'doc';
+  readonly identifier: string;
+} | {
+  readonly kind: 'folder';
+  readonly identifier: string;
+} | {
+  readonly kind: 'asset';
+  readonly identifier: string;
+} | {
+  readonly kind: null;
+};
+/**
+ * Renderer → main snapshot of the View menu's checkbox + smart-hide state.
+ * Sibling of `OkEditorActiveTargetSnapshot`.
+ */
+interface OkEditorViewMenuStateSnapshot {
+  readonly showHiddenFiles: boolean;
+  readonly showOkFolders: boolean;
+  readonly showOnlyMarkdownFiles: boolean;
+  readonly showSkillsSection: boolean;
+  readonly canExpandAll: boolean;
+  readonly canCollapseAll: boolean;
+  readonly sidebarVisible: boolean;
+  readonly docPanelVisible?: boolean;
+  readonly terminalVisible?: boolean;
+  readonly terminalPlacement?: TerminalPlacement;
+  readonly terminalLive?: boolean;
+  readonly agentPanelVisible?: boolean;
+  readonly canViewInSource?: boolean;
+  /**
+   * Is there a live editor selection? ⌘L stages that selection in the agents
+   * panel instead of toggling it, so the menu item has to know: without this the
+   * label reads "Hide Agents" while the click stages a passage and the panel
+   * stays open.
+   */
+  readonly hasEditorSelection?: boolean;
+}
+/**
+ * Windows/Linux renderer-menubar dispatch payloads (the windows-linux-port
+ * renderer-menubar decision). macOS keeps the native menu bar; win/linux draw it in the
+ * renderer and route every click through main via `menu.dispatch` so menu
+ * semantics stay single-sourced: `menu-action` relays through the same
+ * dispatch path the native menu items use, `role` maps onto Electron's
+ * built-in menu roles, `command` covers the main-side click handlers
+ * (navigator, folder picker, settings, updater…), and `query` returns the
+ * aggregated state the native menu renders from. The IPC channel module
+ * re-exports these canonical types under its transport-facing names.
+ */
+type OkMenuDispatchRole = 'undo' | 'redo' | 'cut' | 'copy' | 'paste' | 'selectAll' | 'reload' | 'forceReload' | 'toggleDevTools' | 'resetZoom' | 'zoomIn' | 'zoomOut' | 'toggleFullScreen' | 'minimize' | 'close' | 'quit';
+type OkMenuDispatchCommand = 'open-navigator' | 'open-folder-dialog' | 'clear-recent-projects' | 'open-settings' | 'check-for-updates' | 'reconfigure-mcp-wiring' | 'open-github' | 'toggle-spell-check';
+type OkMenuDispatchRequest = {
+  readonly kind: 'query';
+} | {
+  readonly kind: 'menu-action';
+  readonly action: OkMenuAction;
+} | {
+  readonly kind: 'command';
+  readonly command: OkMenuDispatchCommand;
+} | {
+  readonly kind: 'open-recent-project';
+  readonly path: string;
+} | {
+  readonly kind: 'role';
+  readonly role: OkMenuDispatchRole;
+};
+/** `query` result — the same aggregated state the native menu renders from. */
+interface OkMenuRendererSnapshot {
+  readonly recentProjects: ReadonlyArray<{
+    readonly path: string;
+    readonly name: string;
+  }>;
+  readonly spellCheckEnabled: boolean;
+  readonly showDevToolsMenu: boolean;
+  readonly canCheckForUpdates: boolean;
+  readonly canReconfigureMcpWiring: boolean;
+  readonly activeTarget: OkEditorActiveTargetSnapshot;
+  readonly viewMenuState: OkEditorViewMenuStateSnapshot;
+}
+/** Consent-bearing payload for the renderer-to-main bug-report send hop. */
+interface OkBugReportSendInput {
+  zipPath: string;
+  metadata: OkBugReportSendMetadata;
+  /**
+   * Whether the reviewed bundle contains an app screenshot. The bundle's
+   * inventory is the consent record; absent or false means main must not
+   * upload the capture it may still hold.
+   */
+  includeScreenshot?: boolean;
+}
+/**
+ * Renderer-facing Electron bridge. Populated on `window.okDesktop` by the
+ * desktop preload script. Web distribution omits the
+ * global entirely — consumers MUST use `window.okDesktop?.` optional chaining.
+ *
+ * Method surface is intentionally small: dialog pickers, outbound URL /
+ * clipboard relays, project subscriptions, and the readonly config snapshot.
+ * Broad APIs (window sizing, system info, raw ipcRenderer) are deliberately
+ * omitted — new capabilities cross the preload boundary deliberately, one at
+ * a time, via new typed methods.
+ */
+/** OK config sharing mode. */
+interface OkSharingStatusResult {
+  readonly kind: 'status';
+  readonly mode: 'shared' | 'local-only' | 'no-git';
+  readonly excluded: readonly string[];
+  readonly trackedUpstream: readonly string[];
+  /** True when local-only but `.ok/skills/` is carved back out as shareable. */
+  readonly skillsShared: boolean;
+}
+type OkSharingSetModeResult = {
+  readonly kind: 'applied';
+  readonly mode: 'shared' | 'local-only' | 'no-git';
+} | {
+  readonly kind: 'refused-tracked';
+  readonly tracked: readonly string[];
+  readonly remediation: string;
+} | {
+  readonly kind: 'no-exclude';
+  readonly reason: 'no-git' | 'no-info-dir' | 'malformed-pointer' | 'inaccessible';
+};
+/** Slides (Slidev) — detect-only IPC payload. Canonical types in
+ *  `packages/desktop/src/shared/ipc-channels.ts`; mirrored here per the
+ *  OkDesktopBridge 3-way-mirror invariant. */
+type SlidevSource = 'project-local' | 'global';
+type OkSlidesStatusResult = {
+  readonly kind: 'status';
+  readonly available: true;
+  readonly source: SlidevSource;
+} | {
+  readonly kind: 'status';
+  readonly available: false;
+};
+/** Why opening a deck as slides failed. Canonical types in
+ *  `packages/desktop/src/shared/ipc-channels.ts`; mirrored here. */
+type SlidevOpenFailureReason = 'not-available' | 'invalid-path' | 'spawn-error' | 'exited-early' | 'timeout' | 'unsupported-server';
+type OkSlidesOpenResult = {
+  readonly kind: 'open';
+  readonly ok: true;
+} | {
+  readonly kind: 'open';
+  readonly ok: false;
+  readonly reason: SlidevOpenFailureReason;
+};
+/**
+ * Payload for `onServerVersionDrift` — the desktop attached to a server whose
+ * version differs from the running app's (most often a prior version's
+ * detached server still alive after an auto-update).
+ */
+interface OkServerVersionDriftInfo {
+  /** `older` = the attached server predates the app; `newer` = it is ahead. */
+  readonly relation: 'older' | 'newer';
+  /** Which dimension differed — diagnostic, not surfaced in copy. */
+  readonly dimension: 'protocol' | 'runtime';
+  /** The attached server's runtime semver (for the notification body). */
+  readonly serverRuntime: string;
+  /** The running app's runtime semver. */
+  readonly appRuntime: string;
+}
+/** Payload for `onServerRestarted` — fired on the freshly-spawned window after a successful restart. */
+interface OkServerRestartedInfo {
+  readonly appRuntime: string;
+}
+/**
+ * Payload for `onRecentRemovedMissing` — fired on the window that initiated a
+ * recents open when the target folder was gone and its stale entry was pruned.
+ */
+interface OkRecentRemovedMissingInfo {
+  readonly path: string;
+  readonly projectName: string;
+}
+/**
+ * Result of `restartServer`. Only the failure case reaches the originating
+ * renderer — on success the window is recreated, so its invoke promise never
+ * resolves (by design); the success toast fires on the new window instead.
+ */
+type OkServerRestartOutcome = {
+  readonly ok: true;
+} | {
+  readonly ok: false;
+  readonly reason: 'eperm' | 'other';
+};
+/** Result of `terminal.create`. */
+type OkPtyCreateResult = {
+  readonly ok: true;
+  readonly ptyId: string;
+} | {
+  readonly ok: false;
+  readonly reason: 'no-project' | 'not-consented';
+};
+/** Entry of `terminal.list`. */
+interface OkPtyListEntry {
+  readonly ptyId: string;
+  /** User-set custom tab name that survives a renderer reload; null when unset. */
+  readonly customLabel: string | null;
+  /** Sticky per-session tab number, preserved across a renderer reload; null
+   *  until the renderer has reported it for a just-created session. */
+  readonly ordinal: number | null;
+}
+/** Result of `terminal.adopt`. */
+type OkPtyAdoptResult = {
+  readonly ok: true;
+  readonly replay: string;
+} | {
+  readonly ok: false;
+  readonly reason: 'unknown-session';
+};
+/** Push payload for `ok:pty:data`. */
+interface OkPtyData {
+  readonly ptyId: string;
+  readonly data: string;
+}
+/** Push payload for `ok:pty:exit`. */
+interface OkPtyExit {
+  readonly ptyId: string;
+  readonly exitCode: number;
+  readonly signal: number | null;
+  readonly error?: string;
+}
+/**
+ * Claude Code readiness for the docked terminal.
+ */
+interface ClaudeReadiness {
+  readonly claude: 'present' | 'not-found' | 'unknown';
+  readonly mcp: 'wired' | 'needs-rewire';
+  /** True when the project's own `open-knowledge` `.mcp.json` entry is verified
+   *  to be OK's canonical managed server (cli `isOwnManagedEntry`), so the docked
+   *  terminal may pre-approve it on Claude launch instead of re-showing Claude's
+   *  trust prompt. False/absent for a foreign, tampered, or missing entry (the
+   *  supply-chain risk in a shared/cloned project) — launch bare and let Claude
+   *  prompt. Computed per-project by the desktop preflight; absent means false
+   *  (fail-safe). */
+  readonly mcpPreApprovable?: boolean;
+  /** Set only on a `rewire`-action result when re-arming MCP wiring threw, so
+   *  the renderer can surface the failure instead of the button silently no-op'ing. */
+  readonly rewireError?: string;
+}
+/** On-PATH readiness for a non-Claude agent CLI (codex / cursor-agent) launched
+ *  in the docked terminal. */
+interface CliReadiness {
+  readonly onPath: 'present' | 'not-found' | 'unknown';
+  /** Codex-only: whether OK's `open-knowledge` MCP server is already configured
+   *  in the user's codex config. Gates the per-launch `-c` tool-auto-approve
+   *  override — codex fails to load its config if `-c` targets a server that is
+   *  not defined, so the launch site adds the override only when this is true.
+   *  Absent for CLIs where it does not apply.
+   *
+   *  DELIBERATELY WEAKER THAN CLAUDE'S GATE, and not its security equivalent.
+   *  This is existence-by-name (any object under `mcp_servers.open-knowledge`),
+   *  whereas claude's `mcpPreApprovable` runs `isOwnManagedEntry` to verify the
+   *  entry is byte-exactly OK's own. The asymmetry is sound because the two read
+   *  different files: claude's is a PROJECT-scoped `.mcp.json` that travels in a
+   *  clone, so a same-named foreign entry is a real RCE vector; codex's target is
+   *  `scope: 'global'` (`~/.codex/config.toml`, resolved from `home`, never from
+   *  cwd), so anyone able to plant a foreign entry there can already register
+   *  arbitrary MCP servers and has won regardless. Tightening this to an exact
+   *  ownership match would also fail closed on a legitimate entry carrying any
+   *  extra codex key, silently disabling auto-approve for real users. This gate's
+   *  job is availability (don't break codex's config load), not authorization. */
+  readonly okServerConfigured?: boolean;
+}
+interface OkDesktopBridge {
+  readonly config: OkDesktopConfig;
+  /** Subscribe to project-switch events. Returns unsubscribe. */
+  onProjectSwitched(cb: (next: OkDesktopConfig) => void): OkUnsubscribe;
+  /** Subscribe to menu-bar actions. Returns unsubscribe. */
+  onMenuAction(cb: (action: OkMenuAction) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `autoUpdater` `update-downloaded` events. Fires once per
+   * pending-update version (gated in main by `AppState.versionPendingInstall`).
+   * Returns unsubscribe. Toast A.
+   */
+  onUpdateDownloaded(cb: (info: OkUpdateDownloadedInfo) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `ok:update:relaunching` — another window's "Relaunch now"
+   * click committed in main. Swap this window's `update-downloaded` card to the
+   * button-less "Relaunching…" in-progress state so every window shows
+   * consistent feedback during the pre-`quitAndInstall` server teardown.
+   * Returns unsubscribe.
+   */
+  onUpdateRelaunching(cb: (info: OkUpdateRelaunchingInfo) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `ok:update:relaunch-failed` — a committed relaunch failed
+   * (async updater error, no-quit watchdog, or sync throw). Surface the
+   * relaunch-error notice; the banner re-arm arrives separately as a
+   * re-broadcast `ok:update:downloaded`. Returns unsubscribe.
+   */
+  onUpdateRelaunchFailed(cb: (info: OkUpdateRelaunchFailedInfo) => void): OkUnsubscribe;
+  /**
+   * Subscribe to post-update "What's new" events. Fires once per version
+   * transition on first launch (gated in main by `AppState.lastSeenVersion`).
+   * Returns unsubscribe. Toast B.
+   */
+  onWhatsNew(cb: (info: OkWhatsNewInfo) => void): OkUnsubscribe;
+  /** Subscribe to `ok:update:whats-new-dismissed` — another window dismissed the what's-new notice; clear this window's `whats-new-<version>` card. */
+  onWhatsNewDismissed(cb: (info: {
+    readonly version: string;
+  }) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `stuck-update` hints. Fires at most once per installation
+   * after 7 consecutive failed-check days. Returns unsubscribe. Toast C.
+   */
+  onUpdateStuckHint(cb: (info: OkUpdateStuckHintInfo) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `ok:deep-link` — fired when an
+   * `openknowledge://open?project=…&doc=<name>` URL is routed to this
+   * window. Renderer updates `location.hash` to open the target doc via
+   * the existing hash-route listener. Returns unsubscribe.
+   */
+  onDeepLink(cb: (evt: {
+    doc: string;
+    kind: 'doc' | 'folder';
+    branch?: string | null;
+    multiCandidate?: boolean;
+    targetMissing?: boolean;
+    repositoryPath?: string;
+    contentRootDepth?: number;
+  }) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `ok:share-received` — fired when a share URL (universal
+   * link `https://openknowledge.ai/d/<encoded>` or custom scheme
+   * `openknowledge://share?url=<blob-url>`) routes to this window. The
+   * discriminated payload tells the renderer to mount the receive dialog
+   * (kind `ok`) or surface a toast (kind `unsupported-version` / `invalid`).
+   */
+  onShareReceived(cb: (payload: OkShareReceivedPayload) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `ok:server-version-drift` — fired once when this window
+   * attaches to a server whose version differs from the app's. The renderer
+   * surfaces a cancelable notification offering to restart the server via
+   * `restartServer`.
+   */
+  onServerVersionDrift(cb: (info: OkServerVersionDriftInfo) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `ok:server-restarted` — fired on a freshly-recreated window
+   * after a successful `restartServer`, so the renderer can confirm the
+   * server now matches the app.
+   */
+  onServerRestarted(cb: (info: OkServerRestartedInfo) => void): OkUnsubscribe;
+  /**
+   * Subscribe to `ok:project:recent-removed-missing` — fired on the window that
+   * initiated a recents open of a folder that no longer exists. The stale entry
+   * has already been pruned from the recents list; the renderer surfaces a
+   * lightweight toast (and, in the Navigator, drops the row from its list).
+   */
+  onRecentRemovedMissing(cb: (info: OkRecentRemovedMissingInfo) => void): OkUnsubscribe;
+  /**
+   * Restart the project's server to match this app's version: terminate the
+   * attached (not-owned) server and recreate the window against a fresh
+   * own-version spawn. Resolves to `{ ok:false }` only when termination fails
+   * (the originating window stays); on success the window is recreated and the
+   * success toast fires there.
+   */
+  restartServer(projectPath: string): Promise<OkServerRestartOutcome>;
+  /**
+   * Push the user's chosen `nativeTheme.themeSource` value to main. Carries
+   * the user-intent value (`'system' | 'light' | 'dark'`) verbatim — NEVER
+   * resolve `'system'` to a concrete `'light' | 'dark'` at the call site
+   * (it IS the lever that delegates to macOS appearance). Renderer
+   * ConfigProvider runs this on every CRDT mutation of `appearance.theme`.
+   * Failure is best-effort — body theme stays correct via next-themes; next
+   * CRDT mutation re-fires.
+   */
+  setThemeSource(source: OkThemeSource): Promise<{
+    ok: true;
+  }>;
+  /**
+   * Push the user's chosen interface language to main, which rebuilds the
+   * native menu bar in it. Carries the user-intent value (`'system'` or a
+   * supported tag) verbatim — NEVER resolve `'system'` to a concrete locale at
+   * the call site, for the same reason `setThemeSource` must not: `'system'`
+   * IS the lever that delegates to the OS preferred-language list, and a
+   * resolved value silently stops following it.
+   *
+   * Main resolves the language for its own boot by reading the persisted
+   * preference off disk, because the menu is built before any renderer exists;
+   * this call only carries subsequent changes. Failure is best-effort — the
+   * menu stays on the previous language and the next mutation re-fires.
+   */
+  setLanguagePreference(preference: LanguagePreference): Promise<{
+    ok: true;
+  }>;
+  /**
+   * Fire-and-forget renderer→main signal that the theme has been applied
+   * to chrome. Main's per-window show-gate listens for this alongside
+   * `ready-to-show` before calling `BrowserWindow.show()` — eliminates the
+   * cold-launch staleness window. Implemented in preload as
+   * `invoke('ok:theme:applied', opts).catch(() => {})` so it composes
+   * through the typed `createInvoker` wrapper.
+   *
+   * Optional `opts.reducedTransparency` carries the renderer's live
+   * `matchMedia('(prefers-reduced-transparency: reduce)').matches` value;
+   * main toggles vibrancy material accordingly. `opts.chrome` carries the
+   * active palette's OS-drawn chrome colors.
+   */
+  signalThemeApplied(opts?: {
+    reducedTransparency?: boolean;
+    chrome?: OkChromeColors;
+  }): void;
+  /** Native folder-picker dialog surfaces. */
+  dialog: {
+    /** `dialog.showOpenDialog({ properties: ['openDirectory'] })`. Resolves to the selected path or `null` on cancel.
+     *  `defaultPath` seeds the initial directory shown to the user. */
+    openFolder(opts?: {
+      defaultPath?: string;
+    }): Promise<string | null>;
+  };
+  /**
+   * IPC-relayed wrappers around Electron's `shell` module. Main-process
+   * handlers enforce the outbound-scheme allowlist (`https`, `http`,
+   * `mailto`, `openknowledge`, plus `claude`, `codex`, `cursor` for the
+   * "Open in Agent Desktop" dropdown) before delegating. Unauthorized
+   * schemes reject.
+   */
+  shell: {
+    openExternal(url: string): Promise<void>;
+    /**
+     * Probe whether a URL scheme has a registered handler on this OS.
+     * Used by the "Open in Agent Desktop" dropdown to render disabled-
+     * with-tooltip rows when the target app isn't installed. Returns
+     * `{installed: false}` on timeout or platform-API error.
+     *
+     * **Scheme format contract:** `scheme` is the scheme NAME without
+     * trailing colon (e.g. `'claude'`, not `'claude:'`). Matches the Linux
+     * `xdg-mime query default x-scheme-handler/<name>` shell-command form
+     * and the main-process shell-injection sanitizer — callers with a
+     * colonful scheme MUST strip the trailing `:` first.
+     */
+    detectProtocol(scheme: string): Promise<{
+      installed: boolean;
+      displayName?: string;
+    }>;
+    /**
+     * Step 1 of the Cursor two-step handoff — spawns `cursor <path>` via a
+     * validated argv (shell:false, 2s timeout). Dedicated channel because
+     * the threat model is a command allowlist (PATH hijacking, arg
+     * injection) distinct from the URL-scheme allowlist above.
+     */
+    spawnCursor(path: string): Promise<{
+      ok: true;
+    } | {
+      ok: false;
+      reason: 'invalid-path' | 'not-installed' | 'timeout' | 'spawn-error';
+    }>;
+    /**
+     * Append a local-only telemetry line to `~/.ok/stats.jsonl`. Zero
+     * phone-home. Resolves even if HOME is unwritable — telemetry failure
+     * must never bubble up and affect the dispatch path. The reason and scope
+     * fields use the handoff subsystem's canonical literal-union discriminators.
+     */
+    recordHandoff(line: {
+      readonly target: 'claude-cowork' | 'claude-code' | 'codex' | 'cursor';
+      readonly host: 'electron' | 'web';
+      readonly outcome: 'ok' | 'error';
+      readonly ts: string;
+      readonly reason?: HandoffFailureReason;
+      readonly scope?: HandoffScope;
+    }): Promise<void>;
+    /**
+     * Open an asset via the OS default handler. `relPath` is project-relative
+     * (main-process resolves against `ProjectContext.projectPath` + `realpath` +
+     * `isPathWithinProject`). Executable extensions (`.exe`, `.sh`, `.app`, …)
+     * hard-refuse at the main handler — see
+     * `EXECUTABLE_BLOCKLIST_EXTENSIONS` in `core/constants/upload.ts` for
+     * the full blocklist.
+     */
+    openAsset(relPath: string): Promise<{
+      ok: true;
+    } | {
+      ok: false;
+      reason: 'extension-blocked' | 'path-escape' | 'not-found' | 'resolve-error';
+    }>;
+    /**
+     * Reveal an asset in the native file manager (macOS Finder / Windows
+     * Explorer / Linux xdg-open → default). Parent-only — does NOT invoke
+     * the OS default handler for content. Lower-risk than `openAsset`; the
+     * executable blocklist does NOT apply.
+     */
+    revealAsset(relPath: string): Promise<{
+      ok: true;
+    } | {
+      ok: false;
+      reason: 'path-escape' | 'not-found' | 'resolve-error';
+    }>;
+    /**
+     * Reveal an ABSOLUTE path outside the caller window's project — the
+     * terminal's "this file is outside your project" clickable-link flow.
+     * Deliberately NOT containment-gated (unlike `revealAsset`); main stats the
+     * path and pops a native confirmation dialog, revealing only on confirm. The
+     * dialog is the trust boundary.
+     */
+    revealExternal(absPath: string): Promise<{
+      ok: true;
+      outcome: 'revealed' | 'dismissed';
+    } | {
+      ok: false;
+      reason: 'not-found' | 'invalid-path' | 'error';
+    }>;
+    /**
+     * Display the native right-click context menu for an on-disk reference
+     * (`asset`, `wiki-link`, or `image`). Built from `Menu.buildFromTemplate`
+     * in main — the gesture-attested pattern: main observes the click
+     * directly, no IPC gesture forwarding needed. Entries: Reveal in Finder
+     * + Open in default app + Copy link.
+     */
+    showAssetMenu(params: {
+      readonly relPath: string;
+      readonly title: string;
+      readonly kind: 'asset' | 'wiki-link' | 'image';
+    }): Promise<void>;
+    /**
+     * Reveal a file or folder in the OS file manager (Finder / Explorer /
+     * Linux default). Path is validated against the caller window's project
+     * directory in main; out-of-project, non-absolute, or null-byte-bearing
+     * paths are silently refused at the wire (channel returns `undefined`
+     * regardless; refusals emit a main-process `console.warn` for debugging).
+     */
+    showItemInFolder(path: string): Promise<void>;
+    /**
+     * Move a file or folder to the OS Trash via `shell.trashItem`. Step 1
+     * of the sidebar Delete flow's two-step Option B orchestration.
+     */
+    trashItem(absPath: string): Promise<{
+      ok: true;
+    } | {
+      ok: false;
+      reason: 'not-found' | 'permission-denied' | 'system-error' | 'path-escape';
+      detail?: string;
+    }>;
+  };
+  /** IPC-relayed clipboard writer (sandboxed renderer cannot call clipboard directly). */
+  clipboard: {
+    writeText(text: string): Promise<void>;
+    /**
+     * Copy an image to the clipboard as raster bytes via `nativeImage`,
+     * which macOS's pasteboard writer expands into the 9-flavor raster
+     * set (`«class PNGf»`, `TIFF picture`, `JPEG picture`, `GIF
+     * picture`, `«class jp2»`, `«class BMP»`, `«class TPIC»`,
+     * `«class 8BPS»`, `«class AVIF»`) — the same shape a macOS
+     * screenshot writes. Every rich receiver (Notes, Docs, Slack chat,
+     * Notion inline, iMessage) picks a compatible flavor and renders
+     * inline first-try.
+     *
+     * Renderer's own `navigator.clipboard.write` can't produce that
+     * 9-flavor set (Chromium's Async Clipboard API only accepts one
+     * blob per MIME key), which is why the copy has to run in main.
+     * `nativeImage.createFromBuffer` decodes PNG + JPEG only; other
+     * formats resolve `empty-image` and the renderer is expected to
+     * fall back to its own best-effort `navigator.clipboard.write`.
+     */
+    copyImage(params: {
+      readonly src: string;
+      readonly alt: string;
+    }): Promise<{
+      ok: true;
+    } | {
+      ok: false;
+      reason: 'fetch-failed' | 'path-escape' | 'empty-image' | 'read-error' | 'write-error';
+      detail?: string;
+    }>;
+  };
+  /**
+   * Project-management surface consumed by the Navigator component.
+   * `listRecent` reads the LRU-capped recent list from app state; `open`
+   * spawns a NEW editor window for `request.path` (no switch-in-place);
+   * `close` tears down the window hosting the call site.
+   */
+  project: {
+    listRecent(): Promise<RecentProjectEntry[]>; /** Forget one entry from the recent-projects list. */
+    removeRecent(path: string): Promise<void>;
+    getSessionState(): Promise<ProjectSessionState>;
+    setSessionState(state: ProjectSessionState): Promise<void>;
+    open(request: OkProjectOpenRequest): Promise<void>;
+    /**
+     * File → Open file… — show the native md/mdx picker and open the pick in a
+     * temporary single-file session (the desktop side of `ok <file>`). Picker +
+     * open both run main-side; the picked path never crosses back to the
+     * renderer.
+     */
+    openFile(): Promise<void>;
+    /**
+     * Atomically scaffold a new project under `parent/name` with the
+     * user-chosen `editors` set. `editors` is the renderer's exact selection
+     * (seeded from `integrations.status().detectedEditorIds`, minus/plus
+     * anything the user toggled); main never widens or narrows it.
+     */
+    createNew(args: {
+      parent: string;
+      name: string;
+      editors: OkMcpWiringEditorId[]; /** OK config sharing mode — defaults to 'shared' when omitted. */
+      sharing?: 'shared' | 'local-only';
+      packId?: OkPackId;
+      /**
+       * Folder the pack scaffolds into, relative to the project root.
+       * Omitted → the project root (the dialog's default).
+       */
+      rootDir?: string;
+    }): Promise<void>;
+    /**
+     * Fire-and-forget renderer→main telemetry counter for the Create-new-project
+     * dialog cascade banners.
+     */
+    recordCreateNewBannerShown(banner: CreateNewBannerKind): Promise<void>;
+    /**
+     * Probe `<projectPath>/<path>` for the share-receive target-existence
+     * gate, dispatching the on-disk predicate on `kind`.
+     */
+    checkTargetExists(request: {
+      projectPath: string;
+      kind: 'doc' | 'folder';
+      path: string;
+    }): Promise<OkCheckTargetExistsResult>; /** Read `<projectPath>/.git/HEAD` and classify the result. */
+    readHeadBranch(projectPath: string): Promise<OkHeadBranchInfo>; /** Proxy `GET /api/git/branch-info` against the project's running server. */
+    fetchBranchInfo(request: {
+      projectPath: string;
+      branch: string;
+      kind: 'doc' | 'folder'; /** URL-derived repository-relative target path. */
+      path: string;
+    }): Promise<BranchInfoResponse | null>;
+    /**
+     * Proxy `POST /api/git/checkout` against the project's running server.
+     * `fastForward` (on-origin "Switch and update branch") fast-forwards the
+     * target branch to origin's tip before checkout; divergence → `ff-diverged`
+     * (nothing mutated).
+     */
+    runCheckout(request: {
+      projectPath: string;
+      branch: string;
+      fastForward?: boolean;
+    }): Promise<CheckoutResponse | null>;
+    /**
+     * Proxy `POST /api/share/target-status` for the branch-switch dialog's
+     * verdict pivot.
+     */
+    fetchTargetStatus(request: {
+      projectPath: string;
+      branch: string; /** URL-derived repository-relative target path. */
+      path: string;
+      kind: 'doc' | 'folder'; /** Present only for v2 so rename destinations can be content-relative. */
+      contentRootDepth?: number;
+    }): Promise<ShareTargetStatusResponse | null>;
+    /**
+     * Gate dialog dismissal on the `branch-switched` broadcast landing
+     * in the project window.
+     */
+    awaitBranchSwitched(request: {
+      projectPath: string;
+      branch: string;
+      timeoutMs: number;
+    }): Promise<{
+      ok: true;
+    } | {
+      ok: false;
+      reason: 'timeout' | 'project-not-open';
+    }>; /** Run the share-receive scaffold inside a CLI-managed worktree. */
+    okInit(request: {
+      projectPath: string;
+    }): Promise<LocalOpOkInitResponse>;
+    close(): Promise<void>;
+  };
+  /**
+   * Worktree selector (worktree = window). `list` enumerates the
+   * sender window's project's local branches + their worktrees; `create`
+   * creates (or locates) the worktree for a branch under
+   * `<mainRoot>/.ok/worktrees/`; `checkout` is the share-receive arm
+   * (resolves where the branch lives — fetching from `origin` when
+   * needed — then create-or-locates). Opening a worktree window reuses
+   * `project.open({ entryPoint: 'worktree' })`.
+   */
+  worktree: {
+    list(): Promise<WorktreeListResult>;
+    create(request: WorktreeCreateRequest): Promise<WorktreeCreateResult>;
+    checkout(request: {
+      branch: string;
+    }): Promise<WorktreeCreateResult>;
+  };
+  /**
+   * OK config sharing mode — per-project sharing-mode posture.
+   */
+  sharing: {
+    status(): Promise<OkSharingStatusResult>;
+    setMode(mode: 'shared' | 'local-only'): Promise<OkSharingSetModeResult>; /** Toggle `.ok/skills/` shareability within local-only mode. */
+    setSkillsShared(shared: boolean): Promise<OkSharingSetModeResult>;
+  };
+  /**
+   * Slides (Slidev) — `status` detects a runnable `slidev`; `open` starts (or
+   * reuses) a server for the deck and resolves once it is confirmed serving.
+   * Canonical JSDoc in `packages/desktop/src/shared/ipc-channels.ts`.
+   * Mirrored here per the OkDesktopBridge 3-way-mirror invariant.
+   */
+  slides: {
+    status(): Promise<OkSlidesStatusResult>;
+    open(docPath: string): Promise<OkSlidesOpenResult>;
+  };
+  /**
+   * In-app "Report a bug" — `create` builds the redacted diagnostic zip
+   * (optional crash-dump opt-in via `includeCrashDump`, optional app
+   * screenshot via `includeScreenshot`); `captureScreenshot` grabs the app
+   * before the dialog paints; `send` uploads it with an email fallback;
+   * `onCrashDetected` / `crashAck` carry the crash-invite round-trip.
+   */
+  bugReport: {
+    create(request: {
+      level: ReportBundleLevel$1;
+      note?: string;
+      includeCrashDump?: boolean;
+      includeScreenshot?: boolean;
+    }): Promise<OkBugReportCreateResult>;
+    captureScreenshot(): Promise<OkBugReportScreenshot | null>;
+    /**
+     * Whether main is holding a crash dump this report could carry. Only a
+     * report the user opened themselves needs to ask — a crash invitation
+     * already carries the answer on its event.
+     */
+    crashDumpAvailability(): Promise<OkBugReportCrashDumpAvailability>;
+    send(request: OkBugReportSendInput): Promise<OkBugReportSendResult>;
+    crashAck(request: {
+      eventId: string;
+    }): Promise<OkBugReportCrashAckResult>;
+    list(): Promise<OkBugReportListResult>;
+    delete(id: string): Promise<OkBugReportDeleteResult>;
+    onCrashDetected(cb: (event: OkBugReportCrashDetectedEvent) => void): OkUnsubscribe;
+  };
+  /** Filesystem probes that back the Create-new-project dialog cascade. */
+  fs: {
+    defaultProjectsRoot(): Promise<string>;
+    folderState(path: string): Promise<OkFolderState>;
+    findEnclosingProjectRoot(path: string): Promise<OkFindEnclosingProjectRootResult | null>;
+    findEnclosingGitRoot(path: string): Promise<OkFindEnclosingGitRootResult | null>;
+    removeGitFolder(gitRoot: string): Promise<void>;
+  };
+  /**
+   * Re-summon the Project Navigator window from inside an editor window.
+   * Backed by main's `openNavigator()` helper — focus-existing-or-create
+   * with no toggle semantics. Renderer call sites: `ProjectSwitcher`
+   * dropdown's "Switch Project…" item and `CommandPalette`'s "Switch
+   * Project" entry. The File menu's "Switch Project…" item invokes
+   * `openNavigator()` directly inside main without crossing the bridge.
+   */
+  navigator: {
+    open(): Promise<void>;
+  };
+  /** Popped-out single-document windows (`--ok-mode=note`). */
+  noteWindow: {
+    /**
+     * Pop `docName` out into its own window, or focus the window already
+     * showing it. `no-project` when the calling window has no project context.
+     */
+    open(docName: string, entryPoint: 'tab-menu' | 'palette'): Promise<{
+      ok: true;
+      outcome: 'created' | 'focused';
+    } | {
+      ok: false;
+      reason: 'no-project' | 'invalid-request';
+    }>;
+    /**
+     * Focus the owning project window and deliver a conversation/comments
+     * action there. Note-window renderers call this instead of opening chrome
+     * that deliberately does not exist in their reduced surface.
+     */
+    dispatchToMain(action: OkNoteWindowMainAction): Promise<OkNoteWindowMainActionResult>; /** Receive a note-window action in the owning project renderer. */
+    onMainAction(cb: (action: OkNoteWindowMainAction) => void): OkUnsubscribe;
+  };
+  /**
+   * `ok seed` scaffolder surface consumed by the FileSidebar + menu.
+   * `plan()` is read-only and returns what the scaffolder would write;
+   * `apply(plan)` performs the writes. Same functions run under the
+   * Commander CLI (`ok seed`).
+   */
+  seed: {
+    plan(options?: OkSeedPlanOptions): Promise<OkSeedPlanResult>;
+    apply(plan: OkScaffoldPlan, options?: OkSeedApplyOptions): Promise<OkSeedApplyResult>;
+    listPacks(): Promise<OkSeedListPacksResult>;
+  };
+  /**
+   * Claude Chat & Cowork skill install-dialog hooks. Drives the 2-click
+   * install via Claude.app's `.skill` `CFBundleDocumentType`. Local-build
+   * design: `.skill` is produced on demand from the app-bundled SKILL.md;
+   * no GitHub Releases dep.
+   */
+  skill: {
+    /** True when Claude Desktop's config dir exists on this machine. */detectClaudeDesktop(): Promise<boolean>;
+    /**
+     * Build `openknowledge.skill` from the bundled source, save to
+     * Downloads, invoke the OS file association (`.skill` → Claude
+     * Desktop). Local build; no network.
+     *
+     * Gated by `~/.ok/skill-state/claude-cowork`: when the recorded
+     * version matches the current bundled skill version, resolves with
+     * `{ ok: true, skipped: true, version, recordedAt? }` without
+     * rebuilding. Pass `force: true` to bypass.
+     */
+    buildAndOpen(opts?: {
+      force?: boolean;
+    }): Promise<{
+      ok: true;
+      path: string;
+      skipped?: false;
+      version?: string;
+    } | {
+      ok: true;
+      path?: undefined;
+      skipped: true;
+      version: string;
+      recordedAt?: string;
+    } | {
+      ok: false;
+      reason: 'build-failed' | 'open-failed' | 'no-downloads-dir';
+      message?: string;
+    }>;
+  };
+  /**
+   * Auto-update control surface. Toast A's "Relaunch now" button calls
+   * `relaunchNow()` which invokes `autoUpdater.quitAndInstall()` in main.
+   */
+  update: {
+    relaunchNow(): Promise<void>;
+    /**
+     * Force an out-of-cadence `checkForUpdates()` — fires the
+     * `ok:update:check-now` IPC. Surfaced from the application menu's
+     * "Check for Updates…" entries (App menu on macOS, Help menu
+     * cross-platform). The user-facing result reaches the UI through
+     * the existing toast event subscribers, so this resolves once main
+     * has fired the request rather than waiting on the network.
+     */
+    checkNow(): Promise<void>;
+    /**
+     * Fire `ok:update:whats-new-dismiss` — tells main this window dismissed the
+     * what's-new notice so main clears it across all windows. Fire-and-forget.
+     */
+    dismissWhatsNew(version: string): Promise<void>;
+  };
+  /**
+   * Channel + schema-compatibility state surface. Renderer queries on mount
+   * to render the correct BETA badge / About-panel label and route the
+   * refuse-downgrade UX when a future-build state was rolled back.
+   */
+  state: {
+    query(): Promise<OkStateSnapshot>;
+    resetIncompatible(): Promise<void>;
+  };
+  /**
+   * First-launch MCP consent surface. Renderer mounts `<McpConsentDialog>`
+   * when `onShow` fires; calls `confirm` / `skip` on user action; calls
+   * `signalReady()` once on app mount so main knows a renderer is
+   * subscribed (mount-ack handshake).
+   */
+  mcpWiring: {
+    /** Subscribe to the consent-dialog-show event. Returns unsubscribe. */onShow(cb: (payload: OkMcpWiringShowPayload) => void): OkUnsubscribe; /** Fire a one-way mount-ack event so main's whenRendererReady gate opens. */
+    signalReady(): void;
+    /** User clicked Add. `editorIds` is the subset the user checked;
+     *  `pathInstall` is the PATH toggle (tri-state — see
+     *  `OkMcpWiringConfirmRequest`). */
+    confirm(request: OkMcpWiringConfirmRequest): Promise<OkMcpWiringResult>; /** User clicked Skip (or pressed ESC). */
+    skip(): Promise<OkMcpWiringResult>;
+    /**
+     * Re-arm the consent dialog on demand (File → "Set up OpenKnowledge
+     * integrations…" and the Cmd+K command). Resolves `true` when armed,
+     * `false` when unavailable (non-darwin / unpackaged / arming threw).
+     */
+    reconfigure(): Promise<boolean>;
+  };
+  /**
+   * App-wide spell-check toggle (Edit → "Check spelling while typing" and the
+   * Cmd+K command). `toggle()` flips the flag and resolves to the new enabled
+   * state. Bespoke main-side setting; NOT part of the View-menu-state snapshot.
+   */
+  spellcheck: {
+    toggle(): Promise<boolean>;
+  };
+  /**
+   * Settings → AI tools: live per-component install state + one-component
+   * install/uninstall for OK's global footprint (per-editor MCP entries,
+   * shell-PATH shim, user-global skill bundles). Mutations serialize in main.
+   */
+  integrations: {
+    status(): Promise<OkIntegrationsStatus>;
+    setComponent(request: OkIntegrationsSetRequest): Promise<OkIntegrationsSetResult>;
+  };
+  /**
+   * Settings → This project → AI tools: live per-component install state +
+   * one-component install/uninstall for OK's PROJECT-LOCAL footprint (per-editor
+   * project MCP config files + the project runtime skill) against the project
+   * the requesting window has open. Mutations serialize in main.
+   */
+  projectIntegrations: {
+    status(): Promise<OkProjectIntegrationsStatus>;
+    setComponent(request: OkProjectIntegrationsSetRequest): Promise<OkProjectIntegrationsSetResult>;
+  };
+  /**
+   * Per-project consent dialog surface. Navigator-only.
+   * Renderer mounts a shadcn Dialog when `onShow` fires; calls
+   * `confirm` / `cancel` on user action; calls `signalReady()` once on app
+   * mount so main's mount-ack gate opens. `onToast` fires on freshly-spawned
+   * editor windows for ancestor- and git-root-promote events.
+   */
+  onboarding: {
+    onShow(cb: (payload: OkOnboardingShowPayload) => void): OkUnsubscribe;
+    signalReady(): void;
+    confirm(request: OkOnboardingConfirmRequest): Promise<OkOnboardingResult>;
+    cancel(): Promise<OkOnboardingResult>;
+    probeContent(request: OkOnboardingProbeContentRequest): Promise<OkOnboardingProbeContentResult>;
+    onToast(cb: (payload: {
+      readonly kind: 'ancestor-promote';
+      readonly ancestorPath: string;
+    } | {
+      readonly kind: 'git-root-promote';
+      readonly gitRoot: string;
+      readonly pickedPath: string;
+    } | {
+      readonly kind: 'startup-reclaim';
+      readonly mcp: {
+        readonly status: 'none';
+      } | {
+        readonly status: 'repaired';
+        readonly editors: readonly string[];
+      } | {
+        readonly status: 'failed';
+        readonly editors: readonly string[];
+      };
+      readonly path: {
+        readonly status: 'none';
+      } | {
+        readonly status: 'installed';
+        readonly summary: string;
+      } | {
+        readonly status: 'failed';
+        readonly summary: string;
+      };
+    } | {
+      readonly kind: 'sharing-refused-tracked';
+      readonly tracked: readonly string[];
+      readonly remediation: string;
+    } | {
+      readonly kind: 'sharing-no-git';
+      readonly requestedMode: 'local-only';
+    }) => void): OkUnsubscribe;
+  };
+  /**
+   * Pre-project local-op flows. Required by the Project Navigator window
+   * (no backing API server). Editor windows use the HTTP path; this
+   * surface is unused there.
+   */
+  localOp: {
+    auth: {
+      start(): OkLocalOpStream<OkLocalOpAuthEvent>;
+    };
+    clone: {
+      start(request: {
+        url: string;
+        dir: string;
+        branch?: string | null;
+      }): OkLocalOpStream<OkLocalOpCloneEvent>;
+    };
+    authStatus(request?: {
+      host?: string;
+    }): Promise<OkLocalOpAuthStatusResponse>;
+    authRepos(request?: {
+      host?: string;
+    }): Promise<OkLocalOpAuthReposResponse>;
+  };
+  /**
+   * Share-receive flow surface. `validateLocalFolder` runs the
+   * Q2 "I have it locally" folder validator in the main process via
+   * `validateLocalFolderForShare` from the CLI package.
+   */
+  share: {
+    validateLocalFolder(args: {
+      folderPath: string;
+      host: string;
+      owner: string;
+      repo: string;
+    }): Promise<ShareFolderValidationResult$1>;
+  };
+  /**
+   * Editor area state push surface. Renderer fires
+   * `notifyActiveTargetChanged` once per `activeTarget` transition in
+   * `useDocumentContext()`.
+   */
+  editor: {
+    notifyActiveTargetChanged(target: OkEditorActiveTargetSnapshot): void; /** Fire-and-forget push of the sidebar's view-menu state. */
+    notifyViewMenuStateChanged(state: Partial<OkEditorViewMenuStateSnapshot>): void;
+    /**
+     * Fire-and-forget push keying the window's Chromium background-throttling
+     * to its unsynced work.
+     */
+    notifyBackgroundThrottle(signal: {
+      hasPendingWork: boolean;
+      enabled: boolean;
+    }): void;
+  };
+  /**
+   * Windows/Linux renderer-menubar dispatch surface (windows-linux-port
+   * renderer-menubar decision). macOS keeps the native menu bar and never calls this; on
+   * win/linux the renderer-drawn menu bar routes every click through main
+   * so menu semantics live in one place. `query` resolves the aggregated
+   * `OkMenuRendererSnapshot`; every other kind performs the action
+   * main-side and resolves undefined.
+   */
+  menu: {
+    dispatch(request: OkMenuDispatchRequest): Promise<OkMenuRendererSnapshot | undefined>;
+  };
+  /**
+   * Startup-instrumentation push surface (desktop launch waterfall). The
+   * renderer reports its two launch checkpoints — page-list ready and first
+   * content — as epoch-ms once both land; main folds them into the
+   * `desktop.startup-timeline` log line.
+   */
+  startup: {
+    reportMarks(marks: {
+      pageListReadyMs: number;
+      firstContentMs: number;
+    }): void;
+  };
+  /**
+   * Sidebar tree-state push subscriptions. Main pushes
+   * `ok:sidebar:expand-all` / `ok:sidebar:collapse-all` when the user picks
+   * View → Expand All / Collapse All.
+   */
+  sidebar: {
+    expandAll(cb: () => void): OkUnsubscribe;
+    collapseAll(cb: () => void): OkUnsubscribe;
+  };
+  /** Docked terminal panel surface (bottom or right). */
+  terminal: {
+    create(opts: {
+      cols: number;
+      rows: number;
+      launchCommand?: string;
+    }): Promise<OkPtyCreateResult>;
+    input(ptyId: string, data: string): void;
+    resize(ptyId: string, cols: number, rows: number): void;
+    kill(ptyId: string): Promise<void>;
+    drain(ptyId: string, bytes: number): void; /** Reload-rehydration inventory. */
+    list(): Promise<OkPtyListEntry[]>; /** Reload-rehydration adopt. */
+    adopt(ptyId: string): Promise<OkPtyAdoptResult>;
+    /**
+     * Persist per-session tab metadata (custom name + sticky ordinal) in main so
+     * it survives a renderer reload — main outlives the reload, so a reloaded dock
+     * reads it back via `list`. Fire-and-forget; omit a field to leave it unchanged.
+     */
+    setMeta(ptyId: string, meta: {
+      customLabel?: string | null;
+      ordinal?: number;
+    }): void;
+    /**
+     * Persist the tab display order in main (ptyIds in visual order) so a reorder
+     * survives a renderer reload. Fire-and-forget.
+     */
+    setOrder(orderedPtyIds: readonly string[]): void; /** Per-window state for the independent terminal and agents panels. */
+    getDockState(): Promise<OkTerminalDockState>; /** Persist one panel's session state per window and report durable-write failures. */
+    setDockState(state: OkTerminalDockStateUpdate): Promise<OkTerminalDockStateWriteResult>;
+    onData(cb: (msg: OkPtyData) => void): OkUnsubscribe;
+    onExit(cb: (msg: OkPtyExit) => void): OkUnsubscribe;
+    claudePreflight(): Promise<ClaudeReadiness>;
+    cliPreflight(cli: TerminalCli): Promise<CliReadiness>;
+    /**
+     * Batched on-PATH readiness. An absent key means the probe could not verify
+     * that CLI either way (NOT absence) — consumers must fail open on
+     * `undefined` and reserve gating-off for the positive `false`.
+     */
+    cliInstalledMap(): Promise<Partial<Record<TerminalCli, boolean>>>;
+    rewireClaudeMcp(): Promise<ClaudeReadiness>;
+  };
+  /**
+   * OS assistive-tech signal gating xterm's `screenReaderMode`. Optional in
+   * the renderer contract: session-only
+   * bridges omit it, and consumers treat an absent surface as
+   * screen-reader-active (fail-accessible).
+   */
+  accessibility?: {
+    isScreenReaderActive(): boolean;
+    onScreenReaderChanged(cb: (active: boolean) => void): OkUnsubscribe;
+  };
+  /** Current platform — `process.platform` reported by preload. */
+  readonly platform: 'darwin' | 'win32' | 'linux';
+  /** Electron app version (from main's `app.getVersion()`). */
+  readonly appVersion: string;
+  /**
+   * Named parallel dev-instance label (branch/worktree) when this launch
+   * relocated `userData` to a named sibling — auto-derived from the git
+   * checkout or an explicit `OK_INSTANCE`. Null for the default install and in
+   * web / CLI distribution. Drives the header branch badge.
+   */
+  readonly instanceLabel: string | null;
+  /**
+   * Resolve a dropped `File` to its absolute filesystem path via Electron
+   * `webUtils.getPathForFile` (renderer-side, no IPC). Returns null for a File
+   * with no backing path on disk (e.g. an in-memory clipboard blob). The
+   * docked terminal uses this to insert a dropped file's path at the prompt.
+   */
+  getPathForFile(file: File): string | null;
+  /**
+   * Debug-only namespace — populated by preload ONLY when the
+   * `OK_DEBUG_KEYRING_SMOKE=1` env var is set OR the app is unpacked (dev
+   * mode). Absent in normal production runs.
+   */
+  debug?: {
+    keyringSmoke(): Promise<OkKeyringSmokeResult>;
+  };
+}
+declare global {
+  interface Window {
+    /** Populated by the desktop preload script. Absent in web / CLI distribution. */
+    okDesktop?: OkDesktopBridge;
+  }
+} //# sourceMappingURL=desktop-bridge.d.ts.map
+//#endregion
 //#region src/commands/editors.d.ts
 type EditorId = EditorId$1;
 declare const ALL_EDITOR_IDS: readonly EditorId[];