@inkeep/open-knowledge 0.25.0-beta.1 → 0.25.0-beta.11

package/dist/index.d.mts

@@ -8,25 +8,61 @@ interface GhDetectResult {
 type ExecFileSyncFn = typeof execFileSync;
 type FileExistsFn = (path: string) => boolean;
 interface DetectGhOptions {
+  /** Injectable for tests. */
   _exec?: ExecFileSyncFn;
+  /** Injectable for tests. */
   _fileExists?: FileExistsFn;
 }
+/**
+ * Detect whether `gh` CLI is on PATH (or a known absolute install path) and
+ * currently authenticated. Returns the token from `gh auth token` on success.
+ *
+ * When `host` is provided, scopes the lookup with `--hostname <host>` so a
+ * GHES-only login isn't mistaken for github.com auth (or vice versa). Note
+ * the flag spelling — `gh auth token` rejects `--host` with "unknown flag";
+ * the canonical name is `--hostname` (alias `-h`).
+ *
+ * Lookup order: bare `gh` via `PATH` first (fast path for shell launches),
+ * then `KNOWN_GH_PATHS` in order (only paths that exist on disk are tried).
+ * Stops at the first command that returns a non-empty token.
+ */
 declare function detectGh(host?: string, options?: DetectGhOptions): GhDetectResult;
 //#endregion
 //#region src/auth/token-store.d.ts
+/** Stored credential entry keyed by hostname. */
 interface TokenEntry {
   login: string;
   token: string;
+  /** Default git protocol for this host (default 'https') */
   gitProtocol?: string;
+  /** User display name from OAuth profile, for identity resolution */
   name?: string;
+  /** User email from OAuth profile, for identity resolution */
   email?: string;
 }
+/** Unified token storage API. Both backends implement this interface. */
 interface TokenStore {
+  /** Which storage mechanism is active */
   readonly backend: 'keyring' | 'file';
   get(host: string): Promise<TokenEntry | null>;
   set(host: string, login: string, token: string, extra?: Pick<TokenEntry, 'gitProtocol' | 'name' | 'email'>): Promise<void>;
   clear(host: string): Promise<void>;
 }
+/**
+ * Optional observability hooks for the token store. Kept as plain callbacks so
+ * `token-store` stays logger-agnostic (it's also constructed in the server
+ * push-permission probe path); the credential helper wires these to its file
+ * logger. A keychain read that returns nothing reports `absent`
+ * (errSecItemNotFound); a read that throws — locked keychain, ACL/access
+ * denied, native ABI mismatch — reports `read-error`. A stored entry that
+ * fails to JSON-parse reports `corrupt-entry`. The kinds are indistinguishable
+ * from the returned `null` alone, which is exactly the signal lost when a
+ * credential silently disappears.
+ *
+ * `error` only ever carries a bounded, value-free token: an `Error.name`
+ * (e.g. `SyntaxError`) or a fixed string. Never a full error message — a
+ * parse/keychain error message can echo bytes of the stored credential.
+ */
 interface TokenStoreDiagnostics {
   onKeychainRead?: (info: {
     kind: 'absent' | 'read-error' | 'corrupt-entry';
@@ -38,7 +74,19 @@ interface TokenStoreDiagnostics {
     reason?: string;
   }) => void;
 }
+/**
+ * Create a TokenStore, preferring the OS keychain (via @napi-rs/keyring) and
+ * falling back to a plaintext YAML file at ~/.ok/auth.yml when the
+ * native module cannot be loaded.
+ *
+ * Logs the active backend at INFO level once.
+ */
 declare function createTokenStore(authFile?: string, diag?: TokenStoreDiagnostics): Promise<TokenStore>;
+/**
+ * Push-permission-probe-shaped token store. Returns immediately; defers
+ * the underlying `createTokenStore()` to the first `.get()` call.
+ * Structural shape matches the server's `ProbeTokenStore` interface.
+ */
 declare function makeLazyProbeTokenStore(authFile?: string): {
   get: (host: string) => Promise<{
     token?: string;
@@ -55,27 +103,125 @@ declare const HOSTS_WITH_USER_SKILL_DIR: readonly {
   readonly hostDir: string;
   readonly editorId: CoreEditorId;
 }[];
+/**
+ * MCP install modes for `ok init`-written editor configs.
+ *
+ * - `'published'` (default) — the local platform's resilient chain shape:
+ *   `{command: '/bin/sh', args: ['-l', '-c', CHAIN_V1]}` on macOS/Linux,
+ *   `{command: 'powershell', args: ['-NoProfile', '-NonInteractive',
+ *   '-Command', CHAIN_WIN_V1]}` on Windows.
+ *   Resolves an installed runtime at spawn time. Byte-identical across all
+ *   developer machines of the same platform; detect with `isEntryUpToDate`
+ *   (which recognizes BOTH shapes on every platform).
+ * - `'dev'` — `{command: 'node', args: [<dist/cli.mjs>, 'mcp'], env: {...}}`.
+ *   Used by `--dev-mcp` for monorepo development against a worktree-local CLI.
+ */
 type McpInstallMode = 'published' | 'dev';
 interface McpInstallOptions {
   mode?: McpInstallMode;
+  /**
+   * Platform whose canonical chain shape to emit; defaults to
+   * `process.platform`. Writers never set this — a machine always writes its
+   * own platform's shape; tests inject it to pin either shape on any host.
+   */
+  platformName?: NodeJS.Platform;
+  /**
+   * Skip `writeEditorMcpConfig`'s `isEditorTargetAvailable` check. Default
+   * `ok init` behavior rejects writes for editors whose config dir doesn't
+   * exist — reasonable when the default editor list is being fanned out
+   * without user intent. The Desktop consent dialog shows every editor with
+   * a checkbox and the user explicitly toggles; their click IS the consent,
+   * so the availability check would silently drop the selection.
+   * `writeUserMcpConfigs` sets this to `true`; terminal-invoked `ok init`
+   * never sets it.
+   */
   skipAvailabilityCheck?: boolean;
 }
+/**
+ * True iff the entry matches either platform's chain shape AND embeds that
+ * shape's current version sentinel. Reclaim's no-op gate — only entries that
+ * pass this check are left untouched. Foreign shapes (legacy bare-npx,
+ * bundle-direct, arbitrary customizations, missing/malformed entries) all
+ * resolve `false` and trigger a rewrite.
+ *
+ * BOTH platforms' canonical shapes are recognized on EVERY platform: a
+ * committed project config (`.mcp.json`, `.cursor/mcp.json`, …) written on
+ * one platform must classify as canonical on the other, or the two
+ * platforms' startup reclaim sweeps would rewrite the shared file back and
+ * forth forever. Writers always EMIT the local platform's shape; this
+ * predicate only decides "leave it alone".
+ *
+ * The check is intentionally permissive on the chain body — the sentinel
+ * version stamp is the only invariant. Future chain edits that don't change
+ * the structural contract can keep the sentinel; structural edits (e.g.
+ * adding a new probe branch that changes execution order) must bump that
+ * platform's sentinel so existing-but-stale entries get rewritten.
+ */
 declare function isEntryUpToDate(entry: unknown): boolean;
 declare function buildManagedServerEntry(options?: McpInstallOptions): Record<string, unknown>;
+/**
+ * Security gate for the docked-terminal Claude launch's MCP pre-approval.
+ *
+ * True iff `entry` is structurally IDENTICAL to one of OK's own canonical
+ * PUBLISHED managed entries — the closed two-element set of the Unix shape
+ * (`{command:'/bin/sh', args:['-l', '-c', CHAIN_V1]}`) and the Windows shape
+ * (`{command:'powershell', args:[…, CHAIN_WIN_V1]}`) — with NO extra keys
+ * (an injected `env` on either shape, a different `command`, an appended
+ * chain line). Unlike {@link isEntryUpToDate} — deliberately permissive (sentinel
+ * substring) for the reclaim flow — this is an EXACT match, so it is sound
+ * as a trust boundary: a same-named `mcpServers["open-knowledge"]` entry in
+ * a shared/cloned project's `.mcp.json` that points anywhere else (RCE via
+ * `command`, tool-poisoning via a URL) fails this and is NOT pre-approved,
+ * leaving Claude Code's own "trust this MCP server?" prompt in place.
+ * Dev-mode and version-stale OK entries also fail (safe — the user simply
+ * sees the prompt). The OTHER platform's canonical is accepted by design: it
+ * is byte-exactly OK's own chain, and its interpreter NAME does not resolve
+ * on this platform (`/bin/sh` does not exist on Windows; PowerShell Core on
+ * macOS/Linux installs as `pwsh`, never `powershell`), so pre-approving it
+ * grants nothing an attacker can use. That inertness is load-bearing: a
+ * future canonical that names a cross-platform-resolvable interpreter must
+ * either keep this gate sound or scope it per-platform.
+ */
 declare function isOwnManagedEntry(entry: unknown): boolean;
 interface EditorMcpTarget {
   id: EditorId;
+  /** Human-friendly name for CLI output. */
   label: string;
+  /** Resolve the absolute path to the MCP config file. */
   configPath: (cwd: string, home?: string) => string;
+  /** On-disk config format for this editor. */
   format: 'json' | 'toml';
+  /** Top-level key that holds the server map. */
   topLevelKey: 'mcpServers' | 'servers' | 'mcp_servers' | 'mcp';
+  /**
+   * Optional second-level key nested under `topLevelKey` that holds the server
+   * map, for editors whose config nests it one level deeper — OpenClaw keys
+   * servers at `mcp.servers.<name>`. When set, the JSON upsert/read walk the
+   * `[topLevelKey, serverMapSubKey, serverName]` path; when absent they use the
+   * flat `[topLevelKey, serverName]` every other editor uses. JSON-only.
+   */
   serverMapSubKey?: string;
+  /**
+   * When true, this editor is only ever written if its config root is present
+   * (`detectPath` exists) — the availability check is enforced even in the
+   * consent flow's `skipAvailabilityCheck` path. For a global agent gateway like
+   * OpenClaw that most users don't run, writing `~/.openclaw/openclaw.json` for a
+   * tool that isn't installed is pointless (nothing reads it), so it's gated on
+   * detection everywhere. Editors without this flag keep the default behavior:
+   * `ok init` gates on detection, but an explicit consent-dialog toggle writes.
+   */
   offerOnlyWhenDetected?: boolean;
+  /** Config key used for this project's MCP server entry. */
   serverName: (cwd: string) => string;
+  /** Build the server entry object for this editor. */
   buildEntry: (cwd: string, options?: McpInstallOptions) => Record<string, unknown>;
+  /** Whether the config is project-local or user-global. */
   scope: 'project' | 'global';
+  /** Filesystem path whose existence implies the editor is installed. */
   detectPath?: (cwd: string, home?: string) => string;
+  /** Project-local MCP config path (used for project-scope installs). */
   projectConfigPath?: (cwd: string) => string;
+  /** Project-local Agent Skill entrypoint, when the editor has a known skill surface. */
   projectSkillPath?: (cwd: string) => string;
 }
 declare const EDITOR_TARGETS: Record<EditorId, EditorMcpTarget>;
@@ -95,9 +241,64 @@ interface PreviewResult {
 declare function previewContent(opts: PreviewOptions): PreviewResult;
 //#endregion
 //#region src/integrations/write-project-skill.d.ts
+/**
+ * Guard against project-scope writes that would traverse a symbolic link.
+ * Without this check `writeFileSync` and `mkdirSync` follow symlinks, so a
+ * pre-existing `.mcp.json -> /etc/passwd` (or similar) planted in a cloned
+ * repository would silently overwrite the target file when the user runs
+ * `ok init` inside that directory.
+ *
+ * Refuses two distinct cases:
+ *   1. The target path itself is a symbolic link — refuse regardless of
+ *      where it points; project-scope writes never traverse a symlink at
+ *      the leaf.
+ *   2. The deepest existing ancestor of the target resolves (via realpath)
+ *      outside the project directory — this catches symlinked parent
+ *      directories such as `.cursor -> /etc` whose contents would be
+ *      written into the symlink target rather than the project tree.
+ *
+ * Allows the legitimate case where intermediate symlinks stay contained
+ * inside the project directory.
+ *
+ * Scope: project-scope writes only. User-scope writes intentionally still
+ * follow symlinks because users frequently maintain dotfiles repositories
+ * with `~/.cursor/mcp.json` (and friends) symlinked to a managed location.
+ */
 declare function assertProjectPathSafe(targetPath: string, cwd: string): void;
 //#endregion
 //#region src/sharing/git-exclude.d.ts
+/**
+ * `sharing/git-exclude.ts` — manage the OK artifact set in `.git/info/exclude`.
+ *
+ * Single source of truth for the sharing-mode toggle. The user's posture — share OK config with the team
+ * (default) or keep it local-only on this machine — is encoded ENTIRELY in
+ * `.git/info/exclude`. No parallel registry; `readSharingMode` derives the
+ * mode by checking whether any OK artifact appears in the exclude file.
+ *
+ * Worktree-aware: every read/write resolves the gitdir via
+ * `resolveGitDirDetailed` from `@inkeep/open-knowledge-core` so linked
+ * worktrees (where `<projectRoot>/.git` is a pointer file) write to the
+ * correct `<repo>/.git/worktrees/<name>/info/exclude`, not a non-existent
+ * `<projectRoot>/.git/info/exclude`.
+ *
+ * Every transition to local-only (init `--local-only`, `ok config-sharing unshare`,
+ * desktop create radio, desktop settings panel) flows through
+ * `addOkPathsToGitExclude`. That function runs `probeTrackedOkPaths`
+ * internally and refuses the write when any OK artifact is already tracked
+ * upstream — `.git/info/exclude` cannot hide tracked files, so silently
+ * completing the operation would mislead the user. One probe site, one
+ * refusal site, one diagnostic.
+ */
+/**
+ * Result of an `addOkPathsToGitExclude` / `removeOkPathsFromGitExclude` call
+ * that completed the variant-matching pass against the exclude file.
+ *
+ * `no-exclude` is a sub-typed no-op: the gitdir is unresolvable, the
+ * resolved gitdir has no `info/` dir, the `.git` pointer is malformed, or
+ * the `.git` entry is inaccessible. Callers map each sub-reason to a
+ * different user-facing message; all four are non-fatal for sharing-mode
+ * itself.
+ */
 type ExcludeWriteResult = {
   kind: 'updated';
   appended: string[];
@@ -107,20 +308,124 @@ type ExcludeWriteResult = {
   kind: 'no-exclude';
   reason: 'no-git' | 'no-info-dir' | 'malformed-pointer' | 'inaccessible';
 };
+/**
+ * Refusal returned by `addOkPathsToGitExclude` when one or more candidate
+ * paths are already tracked upstream. Carries the pre-formatted remediation
+ * message so the CLI and desktop surface identical copy.
+ */
 interface TrackedRefusal {
   kind: 'refused-tracked';
+  /** Paths currently tracked upstream (subset of the input `paths`). */
   tracked: string[];
+  /** Pre-formatted, multi-line user-facing diagnostic. */
   remediation: string;
 }
+/** Resolved sharing-mode reading derived from `.git/info/exclude` content. */
 type SharingMode = 'shared' | 'local-only' | 'no-git';
+/**
+ * Return the canonical OK artifact set for a project. Artifact classes:
+ *
+ *  - `.ok/`                              — whole-tree, config + folder configs
+ *  - `.okignore`                         — project ignore file (gitignore syntax)
+ *  - `.mcp.json`                        — Claude Code project MCP (merged file)
+ *  - `.cursor/mcp.json`                 — Cursor project MCP (merged file)
+ *  - `.codex/config.toml`               — Codex project MCP (merged file)
+ *  - `.claude/skills/open-knowledge/`   — Claude project SKILL.md bundle (whole-tree)
+ *  - `.cursor/skills/open-knowledge/`   — Cursor project SKILL.md bundle (whole-tree)
+ *  - `.codex/skills/open-knowledge/`    — Codex project SKILL.md bundle (whole-tree)
+ *  - `.claude/launch.json`              — Claude launcher entry (merged file)
+ *
+ * `.ok/` and `.okignore` are emitted UNANCHORED (slash-free). gitignore
+ * matches a slash-free pattern at every depth, so one entry each covers the
+ * project-root `.ok/` (where `config.yml` lives — it is read from
+ * `<projectRoot>/.ok/`, regardless of `content.dir`), the content-dir copy,
+ * and folder-nested copies. This is intentionally content.dir-independent:
+ * anchoring to `<contentDir>/.ok/` misses the project-root config dir
+ * whenever `content.dir` is a subdirectory, leaving the primary OK config
+ * committable in local-only mode.
+ *
+ * Returns POSIX-separated, project-root-relative paths. Directory entries
+ * carry a trailing `/` so the gitignore syntax in `.git/info/exclude` treats
+ * them as whole-tree excludes; file entries do not.
+ *
+ * Derives the per-editor `projectConfigPath` / `projectSkillPath` slots from
+ * `EDITOR_TARGETS` so a future editor entry with project-scope artifacts
+ * flows through automatically — no hand-maintained list.
+ */
 declare function getOkArtifactPaths(projectRoot: string): readonly string[];
+/**
+ * Append each path to `<gitdir>/info/exclude`, idempotent against the four
+ * recognized variants per path. Runs `probeTrackedOkPaths` FIRST — when any
+ * candidate path is tracked upstream, returns `TrackedRefusal` and does NOT
+ * write. The probe runs at exactly one site (this function) so the
+ * safety check fires uniformly across every transition to local-only.
+ *
+ * Returns `kind: 'updated'` on a successful append-or-noop pass. The
+ * `appended` and `alreadyPresent` arrays partition the input.
+ *
+ * Returns `kind: 'no-exclude'` when the gitdir / info-dir is unresolvable;
+ * callers treat this as a no-op (sharing-mode is a `.git`-only feature, and
+ * a non-git project has nothing to opt out of).
+ */
 declare function addOkPathsToGitExclude(projectRoot: string, paths: readonly string[]): ExcludeWriteResult | TrackedRefusal;
+/**
+ * Remove every line in `<gitdir>/info/exclude` that matches any of the
+ * four recognized variants for any path. Preserves every other line
+ * byte-identical — no whitespace normalization, no reordering, no
+ * surrounding-line touching. The variant set is the same one
+ * `addOkPathsToGitExclude` and `readSharingMode` use, so add-remove-add
+ * cycles round-trip cleanly.
+ *
+ * No tracked-files probe: going local-only → shared cannot create a
+ * tracking conflict (tracking state is orthogonal to the exclude file).
+ */
 declare function removeOkPathsFromGitExclude(projectRoot: string, paths: readonly string[]): ExcludeWriteResult;
+/**
+ * Read the current sharing mode. `local-only` iff at least one variant for
+ * any path in `getOkArtifactPaths(projectRoot)` appears in
+ * `.git/info/exclude`. `shared` when none match. `no-git` when the gitdir
+ * is unresolvable (non-git project, malformed pointer, or inaccessible).
+ *
+ * Pure read — never throws, never writes. Safe to call from the desktop UI
+ * mount path or from CI lockfile scripts.
+ */
 declare function readSharingMode(projectRoot: string): SharingMode;
+/**
+ * Return the subset of `getOkArtifactPaths(projectRoot)` that currently
+ * appears in `.git/info/exclude` (matched via the canonical four-variant
+ * spelling tolerance). Pure read — never writes, never throws. Empty array
+ * when the gitdir is unresolvable.
+ *
+ * Used by `ok config-sharing status` to render the excluded-paths section and by
+ * the desktop settings panel for the equivalent UI list. Lives next to
+ * `readSharingMode` so both observable read paths share one variant-match
+ * implementation — no `excludeFileContains`-style duplicate.
+ */
 declare function getExcludedOkPaths(projectRoot: string): readonly string[];
+/**
+ * Pure probe — checks which of `paths` (if any) are currently tracked
+ * upstream via `git ls-files --error-unmatch`. Used at exactly one site
+ * inside `addOkPathsToGitExclude`, plus by `ok config-sharing status` to surface
+ * the tracked set in the read-only report. Skips paths that don't exist
+ * on disk — there's nothing to potentially conflict.
+ *
+ * `git ls-files --error-unmatch <p>` exits 0 iff at least one index entry
+ * matches the pathspec. Works for both files and directories — the
+ * directory form expands to "any tracked file under this path."
+ */
 declare function probeTrackedOkPaths(projectRoot: string, paths: readonly string[]): {
   tracked: string[];
 };
+/**
+ * Format the tracked-files diagnostic. Single source of truth for the
+ * remediation copy — the CLI prints it to stderr, the desktop modal
+ * renders the same string.
+ *
+ * The hand-crafted shape lists each tracked path, names the exact
+ * `git rm --cached` command for each, and warns about the
+ * teammate-side-effect of an `rm --cached` (the deletion propagates on
+ * next pull). Loud and explicit.
+ */
 declare function formatTrackedRemediation(tracked: readonly string[]): string;
 //#endregion
 //#region src/commands/init.d.ts
@@ -131,11 +436,47 @@ interface EditorMcpResult {
   configPath: string;
   serverName: string;
   error?: string;
+  /**
+   * Set on a 'declined' action: the bounded reason OK left a present config
+   * byte-unchanged rather than register into it (unparseable, oversized, or a
+   * duplicate container key). Engineer-facing; no config contents.
+   */
   declineReason?: McpDeclineReason;
+  /** Set to 'project' when the result came from a project-scope write. */
   configScope?: 'project';
 }
 declare const LAUNCH_CONFIG_NAME = "open-knowledge-ui";
+/**
+ * Version sentinel for the published-mode launch.json recipe. The first line
+ * of the chain doubles as a shell comment and the stamp `classifyLaunchJsonEntry`
+ * matches on. Bump the suffix (`v2`, …) on any structurally-different chain so
+ * the repair sweep recognizes stale text and rewrites it forward.
+ */
 declare const LAUNCH_UI_CHAIN_SENTINEL = "# ok-ui-v1";
+/**
+ * Published-mode `.claude/launch.json` recipe — the preview pane spawns this
+ * to bring the worktree's editor up. Mirrors the proven `# ok-mcp-v1` chain
+ * (editors.ts) — resolves the Desktop bundle first (user → system Applications),
+ * then npx, then version-manager `npx` paths — but runs **`ok start`**, not
+ * bare `ok ui`, so the folder gets its OWN collab server (the worktree fix).
+ * `ok start` connects-instead-of-erroring on a live lock (`--ui-port` path), so
+ * one committed recipe is safe on both the main checkout and a fresh worktree.
+ *
+ * Port handling: the pane passes its watched port via `PORT` env. We capture it
+ * as `UIPORT`, defaulting to the launch.json `port` (`LAUNCH_JSON_PORT`) when
+ * `PORT` is somehow absent — the pane probes that same port, so the default
+ * matches what it watches. `unset PORT` so the collab server kernel-allocates
+ * instead of fighting its UI sibling for the env port (`ok start` also drops
+ * env-`PORT` for the collab when `--ui-port` is set, belt-and-braces). We ALWAYS
+ * pass `--ui-port` — that is what arms `ok start`'s connect-instead-of-exit-1
+ * fallback, so a missing `PORT` can never leave the main checkout running a bare
+ * `ok start` that exits 1 and breaks the preview pane. Ports are numeric;
+ * `"$UIPORT"` is quoted for safety.
+ *
+ * Portable + public-safe: no machine-specific absolute path is baked in; the
+ * bundle is resolved at spawn time. Same chain ships in the git-committed
+ * scaffold and the per-open desktop reclaim (which force-writes this shape).
+ */
 declare const LAUNCH_UI_CHAIN_V1 = "# ok-ui-v1\nUIPORT=\"${PORT:-39848}\"\nunset PORT\nUSER_BUNDLE=\"$HOME/Applications/OpenKnowledge.app/Contents/Resources/cli/bin/ok.sh\"\n[ -f \"$USER_BUNDLE\" ] && [ -x \"$USER_BUNDLE\" ] && exec \"$USER_BUNDLE\" start --ui-port \"$UIPORT\"\nBUNDLE=\"/Applications/OpenKnowledge.app/Contents/Resources/cli/bin/ok.sh\"\n[ -f \"$BUNDLE\" ] && [ -x \"$BUNDLE\" ] && exec \"$BUNDLE\" start --ui-port \"$UIPORT\"\ncommand -v npx >/dev/null 2>&1 && exec npx -y @inkeep/open-knowledge@latest start --ui-port \"$UIPORT\"\nfor d in \"$HOME/.nvm/versions/node\"/*/bin \"$HOME/.fnm/node-versions\"/*/installation/bin \"$HOME/.asdf/installs/nodejs\"/*/bin /opt/homebrew/bin /usr/local/bin \"$HOME/.local/bin\" \"$HOME/.volta/bin\"; do\n  [ -f \"$d/npx\" ] && [ -x \"$d/npx\" ] && exec \"$d/npx\" -y @inkeep/open-knowledge@latest start --ui-port \"$UIPORT\"\ndone\necho \"OpenKnowledge: install OK Desktop or Node.js 24+, then restart your editor\" >&2\nexit 127";
 type LaunchJsonAction = 'created' | 'merged' | 'failed';
 interface LaunchJsonResult {
@@ -143,15 +484,133 @@ interface LaunchJsonResult {
   configPath: string;
   error?: string;
 }
+/**
+ * Scaffold or merge a `.claude/launch.json` entry so that Claude's
+ * built-in preview browser can start the OpenKnowledge dev server via
+ * `preview_start("open-knowledge-ui")`.
+ *
+ * `runtimeArgs` launches `open-knowledge ui` (not `open-knowledge start`) —
+ * the UI sibling-process is what the preview pane renders; collab runs in a
+ * separate `open-knowledge start` process auto-spawned by `ok ui` via the
+ * MCP stdio path.
+ *
+ * - File missing        → create with the OK entry
+ * - File exists, no OK  → merge the entry into configurations
+ * - File exists, has OK → replace with current defaults
+ */
 declare function scaffoldLaunchJson(cwd: string, installOptions?: McpInstallOptions): LaunchJsonResult;
+/**
+ * Per-editor MCP config writer. Exported so `@inkeep/open-knowledge`
+ * consumers — specifically Electron main's first-launch consent flow via
+ * `writeUserMcpConfigs` — can invoke the same write logic that the
+ * terminal-origin `ok init` command uses. The
+ * `installOptions.skipAvailabilityCheck` flag distinguishes the two call
+ * sites: `ok init` enforces `isEditorTargetAvailable` so users don't get
+ * empty config dirs for editors they haven't installed; the consent flow
+ * bypasses the check because the user explicitly toggled the editor
+ * checkbox in the dialog.
+ */
 declare function writeEditorMcpConfig(target: EditorMcpTarget, cwd: string, installOptions: McpInstallOptions, home?: string, configPathOverride?: string): EditorMcpResult;
 interface UserMcpConfigsOptions {
+  /**
+   * Editors whose MCP config to write. Caller (mcp-wiring.ts confirmHandler)
+   * owns user disclosure for any existing `open-knowledge` namespace entry
+   * before calling this writer. This function unconditionally overwrites every
+   * editor it receives (aligning with `writeEditorMcpConfig`'s always-rewrite
+   * semantic — installs stay aligned with current defaults).
+   */
   editors: EditorId[];
+  /** Override `$HOME` for resolving user-scoped config paths (test hook). */
   home?: string;
 }
+/**
+ * Write MCP config entries for a set of editors without any of `runInit`'s
+ * project-scoped side effects.
+ *
+ * Specifically does NOT run:
+ *   - `ensureProjectGit` — would `git init` wherever `cwd` is (packaged Electron
+ *     apps have `process.cwd() === '/'` by default)
+ *   - `initContent` — scaffolds `.ok/` in a project
+ *   - `scaffoldLaunchJson` — writes `.claude/launch.json`
+ *   - `upsertRootInstructions` — mutates `AGENTS.md` / `CLAUDE.md`
+ *   - `collectLegacyProjectConfig` — scans for `.mcp.json` / `.cursor/mcp.json`
+ *
+ * This is the entry point Electron main's first-launch MCP consent flow
+ * calls after the user clicks Add. The terminal-invoked `ok init`
+ * path shares the same canonical npx shape.
+ *
+ * Bypasses `isEditorTargetAvailable` via `skipAvailabilityCheck: true` — the
+ * user explicitly toggled the editor checkbox; their click IS the consent,
+ * so skip-on-missing would silently drop their selection.
+ */
 declare function writeUserMcpConfigs(opts: UserMcpConfigsOptions): Promise<EditorMcpResult[]>;
+/**
+ * Read a single editor's existing MCP server entry for use with the
+ * desktop confirm-flow's canonical-shape classification. Reads the
+ * user-scoped config (format-aware — JSON or TOML), looks up
+ * `config[topLevelKey][serverName]`, and returns it as a plain object.
+ * Returns `null` when the config file is absent, unreadable,
+ * unparseable, or has no entry for this editor's server name.
+ *
+ * **Never-throws contract (load-bearing):** the first-launch consent flow
+ * MUST be able to classify every selected editor without aborting on one
+ * malformed config. A corrupt user config (e.g., stale
+ * `~/.codex/config.toml` from a half-completed third-party edit) on ANY
+ * selected editor would otherwise crash `confirmHandler`, leave the
+ * marker absent, and create an infinite dialog re-fire loop on the user's
+ * machine. Delegates to the never-throwing `classifyExistingMcpEntry`; every
+ * non-`present` classification returns `null`:
+ *   - configPath() throws → null (platform-mismatched target, e.g.
+ *     Claude Desktop on Linux)
+ *   - file absent or blank → null
+ *   - parse fails / duplicate container → `decline` → null (unparseable config)
+ *   - top-level key absent or not a plain object → `no-entry` → null
+ *   - server entry value not a plain object → `no-entry` → null
+ *
+ * Note: `null` deliberately conflates "absent" with "no compatible entry to
+ * merge into" from the desktop classifier's perspective. The downstream
+ * `writeEditorMcpConfig` re-reads via the same capable parser and, on a present
+ * config it can't safely edit, DECLINES (leaves it byte-unchanged) rather than
+ * throwing — surfaced via the bounded `mcp-config-decline` event.
+ */
 declare function readExistingMcpEntry(target: EditorMcpTarget, cwd: string, home?: string, configPathOverride?: string): Record<string, unknown> | null;
+/**
+ * Bounded set of reasons OpenKnowledge declines to register into a present,
+ * non-empty config. Kept to a closed enum (never raw parser text or a config
+ * path) so a decline is observable in telemetry without logging the user's
+ * config contents. `unparseable` covers a genuinely-malformed file, one OK's
+ * parser can't read, or a half-written file caught mid-write by a concurrent
+ * harness — none of which OK's parsers can reliably tell apart, so all collapse
+ * here. `duplicate-container` is produced by the JSON/TOML write paths (an
+ * ambiguous edit target); `oversize` is produced by both the write paths and
+ * `classifyExistingMcpEntry` when a config exceeds the size bound;
+ * `no-native-writer` is the TOML write path declining a present config because
+ * the format-preserving native engine is unavailable and a JS-fallback rewrite
+ * would be lossy — the file was never parsed, so it is not `unparseable`.
+ */
 type McpDeclineReason = 'unparseable' | 'duplicate-container' | 'oversize' | 'no-native-writer';
+/**
+ * Discriminated classification of an existing MCP host config file. Where
+ * `readExistingMcpEntry` collapses every state into `Record | null`, this
+ * surface distinguishes them so callers can act differently per state.
+ *
+ * OpenKnowledge is a guest in another tool's config — its write authority is
+ * scoped to its own entry. A present, non-empty file it cannot parse is
+ * therefore `'decline'`: left untouched, never renamed or overwritten, so a
+ * config OK's parser merely can't read is never mistaken for one to reset.
+ * A `'no-entry'` file (parses, but holds no entry under our server name) is
+ * likewise left alone — it could be an unrelated tool's config.
+ *
+ * Blank / whitespace / 0-byte files classify as `'absent'`: there is nothing
+ * to preserve, so they are safe to create into (the readers already coerce
+ * blank input to `{}` for the merge path). A non-blank file whose parse throws
+ * is `'decline'`, NOT `'absent'` — a half-written file caught mid-write by a
+ * concurrent harness must be left alone, not treated as empty-and-creatable.
+ *
+ * **Never-throws contract:** every failure path returns a structured outcome.
+ * Mirrors `readExistingMcpEntry`'s contract for the same load-bearing reason
+ * (one unreadable user config must not pull the whole startup flow down).
+ */
 type McpEntryClassification = {
   kind: 'absent';
 } | {
@@ -164,6 +623,16 @@ type McpEntryClassification = {
   reason: McpDeclineReason;
 };
 declare function classifyExistingMcpEntry(target: EditorMcpTarget, cwd: string, home?: string, configPathOverride?: string): McpEntryClassification;
+/**
+ * Detect every editor whose global config surface already exists. Each target
+ * can override the probe path when the config file itself is a poor signal
+ * (for example Claude writes `~/.claude.json`, but installation is better
+ * inferred from the presence of `~/.claude/`).
+ *
+ * Used by `runInit()` and the CLI to install to every editor that already has
+ * a config root on disk without creating new user-home directories for tools
+ * the user does not have.
+ */
 declare function detectInstalledEditors(cwd: string, home?: string): EditorId[];
 //#endregion
 //#region src/commands/mcp-decline-event.d.ts
@@ -181,11 +650,42 @@ interface McpConfigDeclineEvent {
   surface: McpConfigDeclineSurface;
   editorId: string;
   reason: McpDeclineReason;
+  /**
+   * Index signature so this type is assignable to the loosely-typed
+   * `event: { event: string; [k: string]: unknown }` parameter the Desktop
+   * structured-event loggers accept — same reason as the migrate event.
+   */
   [key: string]: unknown;
 }
 declare function buildMcpConfigDeclineEvent(input: McpConfigDeclineInput): McpConfigDeclineEvent;
 //#endregion
 //#region src/commands/mcp-migrate-event.d.ts
+/**
+ * Single-source builder for the `mcp-config-migrate` structured event.
+ *
+ * Three surfaces emit this event — CLI `ok start` reclaim, Desktop boot
+ * sweep, Desktop project-open sweep. They predate this builder and used
+ * to ship three different field shapes for the same event name (`editor`
+ * vs `editorId`, `configPath` present/absent, `priorArgs` truncated/not).
+ * That defeated the point of a unified event name: operators who counted
+ * `mcp-config-migrate` aggregated three incompatible schemas. This module
+ * is the only sanctioned construction site.
+ *
+ * Standardized fields:
+ *   - `scope`           — `'user' | 'project'` (cross-surface)
+ *   - `surface`         — free-form identifier of the emitting code path
+ *                         (`'cli-repair'`, `'desktop-startup'`,
+ *                         `'desktop-project-open'`). Always set.
+ *   - `editorId`        — matches `EditorMcpResult.editorId` and
+ *                         `RepairLogEvent.editorId`.
+ *   - `configPath`      — absolute path of the config file being rewritten.
+ *   - `priorCommand`    — truncated to 200 chars or `null` if absent.
+ *   - `priorArgs`       — first 10 entries, each string truncated to 200
+ *                         chars (CHAIN_V1's `args[2]` shell body is ~700
+ *                         chars; without truncation the event payload
+ *                         blows up Tempo/Prometheus label storage and
+ *                         every aggregation downstream).
+ */
 type McpConfigMigrateScope = 'user' | 'project';
 interface McpConfigMigrateInput {
   scope: McpConfigMigrateScope;
@@ -202,9 +702,29 @@ interface McpConfigMigrateEvent {
   configPath: string;
   priorCommand: string | null;
   priorArgs: unknown[] | null;
+  /**
+   * Index signature so this type is assignable to the loosely-typed
+   * `event: { event: string; [k: string]: unknown }` parameter the Desktop
+   * structured-event loggers accept. Future extensions (e.g. a `traceId`
+   * field) don't need a type-system migration in every consumer.
+   */
   [key: string]: unknown;
 }
 declare function buildMcpConfigMigrateEvent(input: McpConfigMigrateInput): McpConfigMigrateEvent;
+/**
+ * Bound the payload of `priorCommand` / `priorArgs` before structured-event
+ * sinks index them. `CHAIN_V1`'s `args[2]` is a ~700-char shell script;
+ * unbounded inclusion in a high-volume metric label explodes downstream
+ * storage.
+ *
+ * Re-exported via `packages/cli/src/index.ts` for workspace-only
+ * consumption — the Desktop `project-mcp-reclaim` sibling event applies
+ * identical bounds. External consumers of `@inkeep/open-knowledge` should
+ * reach for `buildMcpConfigMigrateEvent` instead; this helper is the
+ * inner mechanism, not a stable surface.
+ *
+ * @internal
+ */
 declare function truncatePriorEntry(entry: Record<string, unknown>): {
   priorCommand: string | null;
   priorArgs: unknown[] | null;
@@ -253,6 +773,11 @@ interface StopOutcome {
   }>;
   hadTargets: boolean;
 }
+/**
+ * Execute a stop plan. Exported for tests so they can drive it without
+ * going through Commander. The Commander action wraps this and translates
+ * `failed.length > 0` into `process.exitCode = 1`.
+ */
 declare function runStop(deps: RunStopDeps): StopOutcome;
 //#endregion
 //#region src/config/loader.d.ts
@@ -263,6 +788,29 @@ interface LoadConfigResult {
 declare function loadConfig(cwd?: string): LoadConfigResult;
 //#endregion
 //#region src/github/folder-validator.d.ts
+/**
+ * Validate that a user-picked folder is a clone of the GitHub repo a share
+ * URL points at — drives the "I have it locally →" path on the in-OK receive
+ * dialog. The receive dialog calls this
+ * after the user picks a folder; on `kind: 'ok'` it registers the folder as
+ * a `RecentProject` (with the canonical `gitRemoteUrl`) and opens the doc.
+ *
+ * Symlink discipline mirrors `discoverProject` in
+ * `packages/desktop/src/main/folder-admission.ts`: realpath canonicalize,
+ * then verify the picked folder hasn't escaped via a symlink that resolves
+ * outside its apparent parent. A `.git` directory that symlinks outside the
+ * realpath'd folder is also rejected — the AC's "FR security, inherits OK
+ * Worktree pointers (`.git` is a regular file
+ * containing `gitdir: <path>`) are exempt from the inside-folder check —
+ * legitimate worktrees ALWAYS point at a separate gitdir outside the
+ * worktree folder.
+ *
+ * Owner / repo comparison is case-insensitive: GitHub URLs accept any case
+ * combination (`/Inkeep/Open-Knowledge` and `/inkeep/open-knowledge` resolve
+ * to the same repo), so a clone whose origin uses different case from the
+ * share URL must still match.
+ */
+/** Outcome of `validateLocalFolderForShare`. Discriminated by `kind`. */
 type ShareFolderValidationResult = {
   kind: 'ok';
   gitRemoteUrl: string;
@@ -283,27 +831,53 @@ interface ExpectedShareRepo {
   readonly owner: string;
   readonly repo: string;
 }
+/**
+ * Read the repo's `config` (`<folderPath>/.git/config` for a primary checkout;
+ * for a git-worktree pointer, the shared common dir's config reached via the
+ * worktree gitdir's `commondir` — a linked worktree's gitdir holds no `config`
+ * of its own), parse `[remote "origin"]`, and classify against the expected
+ * `{owner, repo}` from the share URL.
+ *
+ * Never throws — every filesystem or parse failure maps to a structured
+ * result kind so the caller can render a friendly toast.
+ */
 declare function validateLocalFolderForShare(folderPath: string, expected: ExpectedShareRepo): Promise<ShareFolderValidationResult>;
 //#endregion
 //#region src/github/url.d.ts
+/**
+ * Parsed Git URL result.
+ */
 interface ParsedGitUrl {
   protocol: 'https' | 'ssh' | 'git';
   hostname: string;
   owner: string;
   name: string;
 }
+/**
+ * Parsed GitHub blob URL result.
+ */
 interface ParsedGitHubBlobUrl {
   owner: string;
   repo: string;
   branch: string;
   path: string;
 }
+/**
+ * Parsed GitHub tree (folder) URL result. `path` is the folder path relative
+ * to the repo root and MAY be the empty string for a repo/branch root
+ * (`tree/<branch>` or `tree/<branch>/`).
+ */
 interface ParsedGitHubTreeUrl {
   owner: string;
   repo: string;
   branch: string;
   path: string;
 }
+/**
+ * Unified result of the share-URL dispatcher. A GitHub blob URL is a `doc`
+ * target; a GitHub tree URL is a `folder` target (whose `path` may be empty
+ * for the repo/branch root).
+ */
 type ParsedGitHubShareTarget = {
   kind: 'doc';
   owner: string;
@@ -317,13 +891,170 @@ type ParsedGitHubShareTarget = {
   branch: string;
   path: string;
 };
+/**
+ * Parse a git remote URL or shorthand into its components.
+ *
+ * Handles:
+ *   - https://host[:port]/owner/repo[.git]
+ *   - http://host[:port]/owner/repo[.git]
+ *   - ssh://[user@]host[:port]/owner/repo[.git]
+ *   - git://host[:port]/owner/repo[.git]
+ *   - git@host:owner/repo[.git]           (SCP-style SSH)
+ *   - [user@]host.ghe.com:owner/repo[.git] (GHES SCP-style)
+ *   - git:host/owner/repo[.git]            (bare git protocol)
+ *   - owner/repo[.git]                     (shorthand → github.com)
+ *
+ * Returns null for invalid or unrecognised input.
+ */
 declare function parseGitUrl(input: string): ParsedGitUrl | null;
+/**
+ * Parse a GitHub blob URL of the form
+ *   https://github.com/<owner>/<repo>/blob/<branch>/<path...>
+ * into its `{ owner, repo, branch, path }` components.
+ *
+ * Branch slashes must be percent-encoded (`feat%2Ffoo`) — the URL form
+ * `https://github.com/o/r/blob/feat/foo/file.md` is ambiguous between
+ * `branch=feat,path=foo/file.md` and `branch=feat/foo,path=file.md`,
+ * and we cannot disambiguate without a GitHub API call. The sender
+ * encodes; the parser decodes.
+ *
+ * Returns null for any URL that is not a well-formed GitHub blob URL.
+ */
 declare function parseGitHubBlobUrl(input: string): ParsedGitHubBlobUrl | null;
+/**
+ * Parse a GitHub tree (folder) URL of the form
+ *   https://github.com/<owner>/<repo>/tree/<branch>[/<path...>]
+ * into its `{ owner, repo, branch, path }` components.
+ *
+ * Unlike `parseGitHubBlobUrl`, the folder path MAY be empty — `tree/<branch>`
+ * and `tree/<branch>/` both denote the repo/branch root and yield `path: ''`.
+ * (The builder emits no trailing slash; the parser tolerates both
+ * shapes defensively.)
+ *
+ * Branch slashes must be percent-encoded (`feat%2Ffoo`) for the same
+ * disambiguation reason as the blob parser — the sender encodes, the parser
+ * decodes.
+ *
+ * Returns null for any URL that is not a well-formed GitHub tree URL.
+ */
 declare function parseGitHubTreeUrl(input: string): ParsedGitHubTreeUrl | null;
+/**
+ * Dispatch a share URL to its target kind. A GitHub blob URL resolves to a
+ * `doc` target; a GitHub tree URL resolves to a `folder` target. Blob is
+ * tried first because the two prefixes (`/blob/` vs `/tree/`) are mutually
+ * exclusive — a URL can satisfy at most one.
+ *
+ * Returns null when the input is neither a well-formed blob nor tree URL.
+ */
 declare function parseGitHubShareUrl(input: string): ParsedGitHubShareTarget | null;
 //#endregion
+//#region src/integrations/path-shim.d.ts
+/**
+ * The PATH-shim contract — shared by the DESKTOP installer (which writes the
+ * shim) and the CLI reverter (which removes it for `ok uninstall`).
+ *
+ * The desktop app (macOS packaged only) puts `ok` on the user's PATH by:
+ *   - symlinking `~/.ok/bin/{ok,open-knowledge}` at the app's CLI wrapper,
+ *   - writing `~/.ok/env.sh` (prepends `~/.ok/bin` to PATH),
+ *   - injecting a fenced managed block into each shell rc file that sources
+ *     `~/.ok/env.sh`, and
+ *   - recording every change in a manifest at
+ *     `~/Library/Application Support/OpenKnowledge/path-install.json`.
+ *
+ * The install side lives in the desktop package (`main/path-install.ts`), which
+ * imports the fence markers + marker path + marker shape FROM HERE so the
+ * install and revert can never disagree about what a managed block looks like
+ * or where the manifest lives. The CLI can't import desktop (the dependency
+ * runs desktop→cli), so this — the lower layer both share — is the single
+ * source of truth for the contract, and the home of the CLI-side revert.
+ *
+ * The revert itself is deliberately manifest-driven: it strips ONLY the recorded
+ * rc files' managed blocks and removes ONLY the recorded extra symlinks (and
+ * only while they still point at the recorded target), so a user's own PATH
+ * lines and unrelated `ok`-named binaries are never touched.
+ */
+/** Fence opening the managed block in a shell rc file. */
+declare const PATH_SHIM_BEGIN = "# >>> open-knowledge cli >>>";
+/** Fence closing the managed block. */
+declare const PATH_SHIM_END = "# <<< open-knowledge cli <<<";
+/**
+ * Matches the whole fenced managed block (fence-to-fence, incl. its trailing
+ * newline). Multiline + non-greedy so a file with the block anywhere — and only
+ * that block — is stripped. IDENTICAL to the install-side `BLOCK_RE`; the two
+ * MUST stay in lock-step, which is why both sides import this one constant.
+ */
+declare const PATH_SHIM_BLOCK_RE: RegExp;
+/** Diagnostic snapshot of the interactive PATH captured at install time. */
+interface PathDiscovery {
+  capturedAt: string;
+  pathEntries: string[];
+  shellUsed: string;
+  okBinAlreadyOnPath: boolean;
+}
+/**
+ * The user's rc-append consent record. Additive on version-1 markers:
+ * pre-consent markers carry no field, and older builds reading a marker with
+ * the field ignore it. Absence means "no decision recorded" — the desktop
+ * installer then falls back to grandfather evidence (a healthy managed block
+ * already on disk ⇒ granted) or, with no evidence either, leaves the user's
+ * rc files untouched until the first-launch consent dialog decides. The
+ * revert ignores it (`ok uninstall` deletes the whole manifest).
+ */
+interface PathInstallConsent {
+  status: 'granted' | 'declined';
+  at: string;
+}
+/**
+ * The install manifest — the complete record of every PATH change, written to
+ * `~/Library/Application Support/OpenKnowledge/path-install.json`. The revert
+ * reads `rcFiles` (blocks to strip) and `extraSymlinks` (guarded removals);
+ * `binDir` + `envShimPath` live under `~/.ok/` and are swept by the whole-dir
+ * removal.
+ */
+interface PathInstallMarker {
+  version: 1;
+  installedAt: string;
+  bundleVersion: string;
+  bundleWrapperPath: string;
+  binDir: string;
+  envShimPath: string;
+  rcFiles: string[];
+  /** Rc files the user stripped the managed block from — never written to
+   *  again by the installer. */
+  rcOptOuts: string[];
+  pathDiscovery: PathDiscovery | null;
+  extraSymlinks: Array<{
+    path: string;
+    target: string;
+    createdAt: string;
+    kind: 'created' | 'refreshed-our-own';
+  }>;
+  /** Rc-append consent record — see `PathInstallConsent`. `version` stays 1. */
+  consent?: PathInstallConsent;
+}
+/** Absolute path to the PATH-install manifest (macOS layout — the shim is
+ *  macOS-packaged-desktop only, so this path is where it is ever written). */
+declare function pathInstallMarkerPath(home: string): string;
+//#endregion
 //#region src/integrations/project-integration-writers.d.ts
 type IntegrationId = 'mcp-config' | 'project-skill';
+/**
+ * Per-(editor × integration) outcome.
+ *
+ * `action` discriminates five states:
+ *   - `'written'`     — wrote a fresh artifact
+ *   - `'overwritten'` — replaced an existing artifact
+ *   - `'skipped-unsupported'` — editor has no surface for this integration
+ *     (e.g. Claude Desktop has no `projectConfigPath` / no `projectSkillPath`)
+ *   - `'declined'`    — a present config OK can't safely edit was left
+ *     byte-unchanged (guest-ownership); `reason` is the bounded cause. NOT a
+ *     failure — registration was skipped non-destructively.
+ *   - `'failed'`      — error occurred; `error` is set
+ *
+ * `path` is the absolute target path when one is meaningful; absent for
+ * `skipped-unsupported`. `error` is set iff `action === 'failed'`; `reason` is
+ * set iff `action === 'declined'`.
+ */
 interface IntegrationWriteOutcome {
   readonly integration: IntegrationId;
   readonly editorId: EditorId;
@@ -334,6 +1065,33 @@ interface IntegrationWriteOutcome {
 }
 //#endregion
 //#region src/integrations/resolve-project-root.d.ts
+/**
+ * Resolve a CLI project root via ancestor-walk for `.ok/config.yml` first,
+ * git-root promotion second. Mirrors desktop `discoverProject` from
+ * `packages/desktop/src/main/folder-admission.ts` with a flat record shape and
+ * synchronous execution suited to CLI ergonomics — `ok init` calls this
+ * before any filesystem side effect. It is init-only by design: git-root
+ * promotion and the home-dir stop are scaffolding concerns. Lifecycle
+ * commands anchor to an EXISTING project via the CLI preAction hook's
+ * `resolveProjectAnchor` (`findEnclosingProjectRoot` semantics) instead.
+ *
+ * Walk-up rules:
+ *   - Realpath cwd, stop at home, filesystem root, or 30 levels.
+ *   - First `.ok/config.yml` hit wins; cursor != cwd ⇒ ancestorPromoted.
+ *   - No ancestor: try `git rev-parse --show-toplevel`; promote only when the
+ *     resolved root is a strict descendant of homeDir (carve-out for
+ *     hypothetical `~/.git/`).
+ *   - Otherwise: projectRoot = cwd, no promotion (today's CLI behavior).
+ *
+ * `defaultContentDir` is always `'.'` — content scope equals the resolved
+ * `projectRoot`. On git-root promotion the user can still narrow scope via
+ * `config.yml`'s `content.dir`, but the default aligns "opened folder" and
+ * "content dir" so the two never diverge silently.
+ *
+ * Pure of stdout — the caller decides whether to print `[ok] Opened existing
+ * project at …` or a git-root disclosure line based on the returned record
+ * plus its own `existsSync(<projectRoot>/.ok)` probe.
+ */
 interface ResolveProjectRootResult {
   /** Where `.ok/` lives or will live. Equals `realpath(cwd)` when no
    * promotion happened; otherwise the ancestor that owned `.ok/config.yml`
@@ -344,6 +1102,7 @@ interface ResolveProjectRootResult {
    * NOT used as a default scope — `projectRoot` and content scope align by
    * default; the user can narrow via `content.dir` post-init. */
   readonly defaultContentDir: string;
+  /** True iff a `.ok/` was found above `cwd`. */
   readonly ancestorPromoted: boolean;
   /** True iff the git working-tree root sat above `cwd` and won the
    * promotion (no ancestor `.ok/`). Mutually exclusive with
@@ -359,6 +1118,11 @@ interface ResolveProjectRootOptions {
    * to avoid spinning up real git fixtures for unit-level coverage. */
   gitTopLevel?: (cwd: string) => string | null;
 }
+/**
+ * Classify `cwd` for the CLI scaffolding decision. See module docstring for
+ * the rule order; the result fully describes which `projectRoot` and
+ * `content.dir` value the caller should use.
+ */
 declare function resolveProjectRoot(cwd: string, opts?: ResolveProjectRootOptions): ResolveProjectRootResult;
 //#endregion
 //#region src/integrations/write-project-ai-integrations.d.ts
@@ -372,5 +1136,5 @@ interface ProjectAiIntegrationsResult {
 }
 declare function writeProjectAiIntegrations(projectDir: string, selectedEditorIds: readonly EditorId[], installOptions?: McpInstallOptions): ProjectAiIntegrationsResult;
 //#endregion
-export { ALL_EDITOR_IDS, EDITOR_LABELS, EDITOR_TARGETS, type EditorId, type EditorMcpResult, type EditorMcpTarget, type ExcludeWriteResult, type ExpectedShareRepo, type GhDetectResult, HOSTS_WITH_USER_SKILL_DIR, type IntegrationWriteOutcome, LAUNCH_CONFIG_NAME, LAUNCH_UI_CHAIN_SENTINEL, LAUNCH_UI_CHAIN_V1, type LaunchJsonResult, type LoadConfigResult, type McpConfigDeclineEvent, type McpConfigDeclineScope, type McpConfigMigrateEvent, type McpConfigMigrateScope, type McpDeclineReason, type McpEntryClassification, type McpInstallOptions, type ParsedGitHubBlobUrl, type ParsedGitHubShareTarget, type ParsedGitHubTreeUrl, type PreviewResult, type ProjectAiIntegrationsResult, type ResolveProjectRootOptions, type ResolveProjectRootResult, type ShareFolderValidationResult, type SharingMode, type TokenStore, type TrackedRefusal, type UserMcpConfigsOptions, addOkPathsToGitExclude, assertProjectPathSafe, buildManagedServerEntry, buildMcpConfigDeclineEvent, buildMcpConfigMigrateEvent, classifyExistingMcpEntry, createTokenStore, detectGh, detectInstalledEditors, formatTrackedRemediation, getExcludedOkPaths, getOkArtifactPaths, isEntryUpToDate, isOwnManagedEntry, loadConfig, makeLazyProbeTokenStore, parseGitHubBlobUrl, parseGitHubShareUrl, parseGitHubTreeUrl, parseGitUrl, previewContent, probeTrackedOkPaths, readExistingMcpEntry, readSharingMode, removeOkPathsFromGitExclude, resolveProjectRoot, runStop, scaffoldLaunchJson, truncatePriorEntry, validateLocalFolderForShare, writeEditorMcpConfig, writeProjectAiIntegrations, writeUserMcpConfigs };
+export { ALL_EDITOR_IDS, EDITOR_LABELS, EDITOR_TARGETS, type EditorId, type EditorMcpResult, type EditorMcpTarget, type ExcludeWriteResult, type ExpectedShareRepo, type GhDetectResult, HOSTS_WITH_USER_SKILL_DIR, type IntegrationWriteOutcome, LAUNCH_CONFIG_NAME, LAUNCH_UI_CHAIN_SENTINEL, LAUNCH_UI_CHAIN_V1, type LaunchJsonResult, type LoadConfigResult, type McpConfigDeclineEvent, type McpConfigDeclineScope, type McpConfigMigrateEvent, type McpConfigMigrateScope, type McpDeclineReason, type McpEntryClassification, type McpInstallOptions, PATH_SHIM_BEGIN, PATH_SHIM_BLOCK_RE, PATH_SHIM_END, type ParsedGitHubBlobUrl, type ParsedGitHubShareTarget, type ParsedGitHubTreeUrl, type PathDiscovery, type PathInstallConsent, type PathInstallMarker, type PreviewResult, type ProjectAiIntegrationsResult, type ResolveProjectRootOptions, type ResolveProjectRootResult, type ShareFolderValidationResult, type SharingMode, type TokenStore, type TrackedRefusal, type UserMcpConfigsOptions, addOkPathsToGitExclude, assertProjectPathSafe, buildManagedServerEntry, buildMcpConfigDeclineEvent, buildMcpConfigMigrateEvent, classifyExistingMcpEntry, createTokenStore, detectGh, detectInstalledEditors, formatTrackedRemediation, getExcludedOkPaths, getOkArtifactPaths, isEntryUpToDate, isOwnManagedEntry, loadConfig, makeLazyProbeTokenStore, parseGitHubBlobUrl, parseGitHubShareUrl, parseGitHubTreeUrl, parseGitUrl, pathInstallMarkerPath, previewContent, probeTrackedOkPaths, readExistingMcpEntry, readSharingMode, removeOkPathsFromGitExclude, resolveProjectRoot, runStop, scaffoldLaunchJson, truncatePriorEntry, validateLocalFolderForShare, writeEditorMcpConfig, writeProjectAiIntegrations, writeUserMcpConfigs };
 //# sourceMappingURL=index.d.mts.map