peaks-loop 4.0.15 → 4.0.17

package/dist/services/code-review/ocr-service.js

@@ -1,372 +0,0 @@
-/**
- * Open Code Review (ocr) integration — soft-optional augmentation
- * for peaks-rd's Gate B3 (code review evidence).
- *
- * Per the "skill-first / CLI-auxiliary" tenet, peaks-rd SKILL.md
- * is the primary surface; this CLI primitive returns a structured
- * JSON envelope the skill consumes to produce a second-opinion
- * code review alongside its own LLM review.
- *
- * Mirrors the ECC 64-agents soft-optional pattern
- * (`src/services/agent/ecc-agent-service.ts`):
- *   - same subprocessRunner injection seam (testability),
- *   - same multi-state reason enum (clear failure-mode reporting),
- *   - same soft-fail policy (never blocks the umbrella).
- *
- * === Source of truth: peaks-loop's own config.json ===
- *
- * peaks-loop does NOT auto-configure the LLM endpoint, and it does
- * NOT write `~/.opencodereview/config.json`. The user is the only
- * party that touches their LLM token / URL / model. The single
- * discoverable place they declare those values is
- * `peaksConfig.ocr.llm` under their `~/.peaks/config.json` (or
- * `.peaks/config.json` in a project root).
- *
- *   peaksConfig.ocr.llm.url          → OCR_LLM_URL
- *   peaksConfig.ocr.llm.authToken    → OCR_LLM_TOKEN
- *   peaksConfig.ocr.llm.model        → OCR_LLM_MODEL
- *   peaksConfig.ocr.llm.useAnthropic → OCR_USE_ANTHROPIC
- *   peaksConfig.ocr.llm.authHeader   → OCR_LLM_AUTH_HEADER
- *
- * When `runOcrReview` spawns the ocr subprocess it injects those
- * values as env vars. The ocr package treats env vars as the
- * highest-priority config source, so peaks-loop never has to
- * materialise `~/.opencodereview/config.json` itself.
- *
- * To see the JSON template to paste, run:
- *   `peaks code-review config-template`
- *
- * The ocr package is declared in package.json:peerDependencies
- * (was promoted to `dependencies` in 2.0.1, demoted to
- * `optionalDependencies` in 2.0.3, then to `peerDependencies` in
- * 2.8.2 — the ocr postinstall downloads a Go binary via HTTPS,
- * which fails in restricted/proxied environments and would
- * otherwise slow or abort the whole `npm i -g peaks-loop` flow).
- * Peaks-cli ships with ocr *not* installed; if the user wants it,
- * they run
- *   `npm i -g @alibaba-group/open-code-review`
- * and peaks-loop's 5-state detector (below) reports whether the
- * binary is actually usable. pnpm-based installs additionally need
- * `pnpm approve-builds @alibaba-group/open-code-review` for the
- * binary download to run. Either way, peaks-loop never blocks on it.
- */
-import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { dirname } from 'node:path';
-const OCR_DETECT_TIMEOUT_MS = 5000;
-const OCR_REVIEW_TIMEOUT_MS = 180000;
-const OCR_INSTALL_HINT = 'Install: `npm i -g @alibaba-group/open-code-review` (peaks-loop 2.8.2 ships with ocr as a peer dependency — its postinstall downloads a Go binary via HTTPS, which fails in some restricted/proxied environments; that\'s why peaks-loop does not auto-install it). Then add your LLM endpoint to ~/.peaks/config.json — run `peaks code-review config-template` for the JSON snippet to paste. Under pnpm you also need `pnpm approve-builds @alibaba-group/open-code-review` to allow the binary download.';
-const OCR_CONFIG_TEMPLATE = JSON.stringify({
-    ocr: {
-        llm: {
-            url: 'https://api.example.com/v1/messages',
-            authToken: '<your-api-key>',
-            model: 'claude-3-5-sonnet-latest',
-            useAnthropic: true,
-            authHeader: 'x-api-key'
-        }
-    }
-}, null, 2);
-const DEFAULT_RUNNER = {
-    run(command, args, options) {
-        try {
-            const r = spawnSync(command, args, {
-                encoding: 'utf8',
-                stdio: ['ignore', 'pipe', 'pipe'],
-                timeout: options.timeoutMs,
-                cwd: options.cwd,
-                env: options.env,
-            });
-            return {
-                status: r.status,
-                stdout: r.stdout ?? '',
-                stderr: r.stderr ?? '',
-            };
-        }
-        catch (err) {
-            return {
-                status: null,
-                stdout: '',
-                stderr: '',
-                error: err instanceof Error ? err.message : String(err),
-            };
-        }
-    },
-};
-/**
- * Locate the ocr launcher script (`bin/ocr.js`) inside our own
- * node_modules tree. Returns null when the npm package is not
- * present (peaks-loop was installed but its dependency tree is
- * corrupt, or the user removed it).
- *
- * Walks up from this file (dist/services/code-review/) to
- * find the project root, then checks node_modules.
- */
-export function resolveOcrLauncher(searchRoots) {
-    const candidates = [];
-    for (const root of searchRoots) {
-        candidates.push(join(root, 'node_modules', '@alibaba-group', 'open-code-review', 'bin', 'ocr.js'));
-    }
-    for (const candidate of candidates) {
-        if (existsSync(candidate)) {
-            return candidate;
-        }
-    }
-    return null;
-}
-/**
- * Resolve search roots for the ocr launcher. We look in two
- * places: (1) the peaks-loop install root (next to our own dist/),
- * (2) the user's cwd.
- */
-export function defaultOcrSearchRoots(currentDirPath, cwd) {
-    // currentDirPath is dist/services/code-review/ under tsc rootDir=src;
-    // walk up 3 to repo root. If tsconfig.build.json#rootDir ever reverts
-    // to "." (emits dist/src/services/code-review/), this must become
-    // walk-4 — keep these two in lockstep.
-    const peaksRoot = join(currentDirPath, '..', '..', '..');
-    return [peaksRoot, cwd];
-}
-/**
- * Validate the `peaksConfig.ocr.llm` block the caller (CLI / test)
- * read out of `~/.peaks/config.json`. Returns the list of missing
- * required keys (`url`, `authToken`, `model`); empty array means
- * the block is ready to drive the ocr subprocess.
- *
- * The block is independent of the OCR package's own
- * `~/.opencodereview/config.json` file. peaks-loop only ever reads
- * from its own config; the env-var injection in `runOcrReview`
- * makes the legacy file irrelevant.
- */
-export function getOcrLlmMissingFields(llm) {
-    if (llm === null) {
-        return ['ocr.llm.url', 'ocr.llm.authToken', 'ocr.llm.model'];
-    }
-    const missing = [];
-    if (typeof llm.url !== 'string' || llm.url.length === 0)
-        missing.push('ocr.llm.url');
-    if (typeof llm.authToken !== 'string' || llm.authToken.length === 0)
-        missing.push('ocr.llm.authToken');
-    if (typeof llm.model !== 'string' || llm.model.length === 0)
-        missing.push('ocr.llm.model');
-    return missing;
-}
-/**
- * Build the env-var overlay peaks-loop injects into the ocr
- * subprocess. Maps `peaksConfig.ocr.llm` onto the OCR package's
- * env-var surface (its highest-priority config source).
- */
-export function buildOcrEnv(llm) {
-    const env = {};
-    if (typeof llm.url === 'string' && llm.url.length > 0)
-        env.OCR_LLM_URL = llm.url;
-    if (typeof llm.authToken === 'string' && llm.authToken.length > 0)
-        env.OCR_LLM_TOKEN = llm.authToken;
-    if (typeof llm.model === 'string' && llm.model.length > 0)
-        env.OCR_LLM_MODEL = llm.model;
-    if (typeof llm.useAnthropic === 'boolean')
-        env.OCR_USE_ANTHROPIC = String(llm.useAnthropic);
-    if (typeof llm.authHeader === 'string' && llm.authHeader.length > 0)
-        env.OCR_LLM_AUTH_HEADER = llm.authHeader;
-    return env;
-}
-/**
- * The JSON template the user pastes into their peaks-loop config
- * (`peaksConfig.ocr.llm`). Returned as a stable string so the
- * `peaks code-review config-template` CLI command can print it
- * verbatim, and so the detector's `nextActions` payload embeds
- * the same shape the user is told to add.
- */
-export function getOcrConfigTemplate() {
-    return OCR_CONFIG_TEMPLATE;
-}
-/**
- * Detect the full ocr install + config state. The 5 reason states
- * are unchanged from the soft-optional 2.0.0 contract; only the
- * source of `config-missing` moved from `~/.opencodereview/config.json`
- * to `peaksConfig.ocr.llm`.
- */
-export function detectOcr(options) {
-    const currentDirPath = dirname(fileURLToPath(import.meta.url));
-    const roots = options.searchRoots ?? defaultOcrSearchRoots(currentDirPath, options.cwd);
-    const launcher = resolveOcrLauncher(roots);
-    const warnings = [];
-    const nextActions = [];
-    if (launcher === null) {
-        const missing = getOcrLlmMissingFields(options.peaksOcrConfig);
-        return {
-            state: 'package-missing',
-            packageInstalled: false,
-            binaryPath: null,
-            version: null,
-            configPath: options.peaksConfigPath,
-            configValid: missing.length === 0,
-            missingKeys: missing,
-            warnings,
-            nextActions: [
-                '@alibaba-group/open-code-review is not installed in this project or peaks-loop root.',
-                OCR_INSTALL_HINT,
-            ],
-        };
-    }
-    // Check whether the platform-specific binary downloaded
-    // successfully. The launcher's own check is identical:
-    // bin/opencodereview(.exe) next to bin/ocr.js.
-    const isWindows = process.platform === 'win32';
-    const binaryName = isWindows ? 'opencodereview.exe' : 'opencodereview';
-    const binaryPath = join(dirname(launcher), binaryName);
-    if (!existsSync(binaryPath)) {
-        const missing = getOcrLlmMissingFields(options.peaksOcrConfig);
-        return {
-            state: 'binary-missing',
-            packageInstalled: true,
-            binaryPath: null,
-            version: null,
-            configPath: options.peaksConfigPath,
-            configValid: missing.length === 0,
-            missingKeys: missing,
-            warnings: [
-                'ocr npm package is installed but the platform binary failed to download (likely network or postinstall blocked).',
-            ],
-            nextActions: [
-                'For npm installs the binary downloads automatically; for pnpm run: `pnpm approve-builds @alibaba-group/open-code-review`.',
-                'Or run the installer directly: `node node_modules/@alibaba-group/open-code-review/scripts/install.js`.',
-                'Network-blocked installs can pre-download from https://github.com/alibaba/open-code-review/releases and place the binary at: ' + binaryPath,
-            ],
-        };
-    }
-    // Probe the binary for its version. We invoke through the
-    // node launcher so the upstream's update-check + arg-parse
-    // logic stays canonical.
-    const runner = options.runner ?? DEFAULT_RUNNER;
-    const probe = runner.run('node', [launcher, 'version'], { timeoutMs: OCR_DETECT_TIMEOUT_MS });
-    let version = null;
-    if (probe.status === 0 && probe.stdout.length > 0) {
-        const match = /(\d+\.\d+\.\d+)/.exec(probe.stdout);
-        version = match !== null ? match[1] ?? null : probe.stdout.trim().slice(0, 32);
-    }
-    const missing = getOcrLlmMissingFields(options.peaksOcrConfig);
-    if (missing.length > 0) {
-        return {
-            state: 'config-missing',
-            packageInstalled: true,
-            binaryPath,
-            version,
-            configPath: options.peaksConfigPath,
-            configValid: false,
-            missingKeys: missing,
-            warnings: [
-                `ocr is installed but peaks-loop's ocr.llm config is incomplete: missing ${missing.join(', ')}.`,
-            ],
-            nextActions: [
-                `Paste the following into ${options.peaksConfigPath} under "ocr.llm":`,
-                OCR_CONFIG_TEMPLATE,
-                'Or run `peaks code-review config-template` to print the snippet again.',
-                'Until configured, peaks-rd skips the ocr second-opinion step and proceeds with its own LLM review only.',
-            ],
-        };
-    }
-    return {
-        state: 'ready',
-        packageInstalled: true,
-        binaryPath,
-        version,
-        configPath: options.peaksConfigPath,
-        configValid: true,
-        missingKeys: [],
-        warnings,
-        nextActions,
-    };
-}
-/**
- * Run ocr review and return the structured result. Detects state
- * first; soft-fails when ocr isn't ready (the caller — typically
- * peaks-rd — proceeds without the second-opinion review).
- *
- * The LLM endpoint config from `peaksConfig.ocr.llm` is injected
- * as env vars (`OCR_LLM_URL` / `OCR_LLM_TOKEN` / ...), which the
- * ocr package treats as the highest-priority config source. This
- * is how peaks-loop wires the user-managed config into the ocr
- * subprocess without ever writing `~/.opencodereview/config.json`.
- */
-export function runOcrReview(options) {
-    const detect = detectOcr(options);
-    if (detect.state !== 'ready') {
-        return {
-            spawned: false,
-            state: detect.state,
-            exitCode: null,
-            stdout: '',
-            stderr: '',
-            durationMs: 0,
-            parsed: null,
-            warnings: detect.warnings,
-            nextActions: detect.nextActions,
-        };
-    }
-    // Resolve the launcher path again (we know it exists because detect.state === 'ready')
-    const currentDirPath = dirname(fileURLToPath(import.meta.url));
-    const roots = options.searchRoots ?? defaultOcrSearchRoots(currentDirPath, options.cwd);
-    const launcher = resolveOcrLauncher(roots);
-    if (launcher === null) {
-        // Should never happen given state === 'ready', but stay safe.
-        return {
-            spawned: false,
-            state: 'detection-failed',
-            exitCode: null,
-            stdout: '',
-            stderr: 'ocr launcher disappeared between detect and run',
-            durationMs: 0,
-            parsed: null,
-            warnings: ['ocr was detected as ready but the launcher path is no longer resolvable.'],
-            nextActions: ['Re-run `peaks code-review detect-ocr --json` to refresh.'],
-        };
-    }
-    // Inject the LLM endpoint config from peaks-loop's config.json
-    // as env vars — the ocr package's highest-priority config path.
-    const env = options.peaksOcrConfig === null
-        ? process.env
-        : { ...process.env, ...buildOcrEnv(options.peaksOcrConfig) };
-    const args = ['review', '--format', 'json'];
-    if (typeof options.input.from === 'string' && options.input.from.length > 0) {
-        args.push('--from', options.input.from);
-    }
-    if (typeof options.input.to === 'string' && options.input.to.length > 0) {
-        args.push('--to', options.input.to);
-    }
-    if (typeof options.input.commit === 'string' && options.input.commit.length > 0) {
-        args.push('--commit', options.input.commit);
-    }
-    const runner = options.runner ?? DEFAULT_RUNNER;
-    const start = Date.now();
-    const r = runner.run('node', [launcher, ...args], {
-        cwd: options.input.projectRoot,
-        timeoutMs: OCR_REVIEW_TIMEOUT_MS,
-        env,
-    });
-    const durationMs = Date.now() - start;
-    let parsed = null;
-    if (r.status === 0 && r.stdout.length > 0) {
-        try {
-            parsed = JSON.parse(r.stdout);
-        }
-        catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
-            // Leave parsed=null; the caller can read raw stdout.
-        }
-    }
-    return {
-        spawned: true,
-        state: 'ready',
-        exitCode: r.status,
-        stdout: r.stdout,
-        stderr: r.stderr,
-        durationMs,
-        parsed,
-        warnings: r.status === 0 ? [] : [`ocr review exited with status ${r.status}`],
-        nextActions: r.status === 0
-            ? []
-            : ['Inspect stderr for the failure. Re-run `peaks code-review detect-ocr --json` to verify config still valid.'],
-    };
-}

package/skills/bee/peaks-rd/references/ocr-integration.md

@@ -1,229 +0,0 @@
-# OCR (Open Code Review) integration
-
-> Soft-optional second-opinion code review for peaks-rd Gate B3.
-> Mirrors the ECC 64-agents pattern (spec §7.2): peaks-loop ships
-> `@alibaba-group/open-code-review` as an **`optionalDependency`**
-> (was promoted to `dependencies` in 2.0.1 and reverted in 2.0.3
-> because its postinstall downloads a Go binary via HTTPS and would
-> otherwise abort `npm i -g peaks-loop` in restricted/proxied
-> environments). The LLM endpoint config still lives under
-> `peaksConfig.ocr.llm` in the user's `~/.peaks/config.json` (single
-> source of truth, user-managed). When the user installs + configures
-> ocr, the wrapper turns its output into structured `code-review.md`
-> evidence; when missing, peaks-rd proceeds LLM-only and the slice
-> ships without the second opinion.
-
-## What ocr is
-
-[Open Code Review](https://github.com/alibaba/open-code-review) is
-an AI-powered code review CLI from Alibaba. It reads git diffs,
-sends the changed files to a **user-configured LLM endpoint**
-(OpenAI- or Anthropic-compatible), and emits structured
-line-precise review comments. It is NOT a hosted service —
-all LLM traffic goes to the user's own configured endpoint.
-
-Distribution: npm `@alibaba-group/open-code-review` (Go binary
-inside; the npm postinstall downloads the platform-specific
-binary from GitHub Releases).
-
-## Why peaks-rd uses it (soft-optional)
-
-The default peaks-rd code-review evidence is produced by the
-main RD LLM (or the `code-reviewer` sub-agent in the parallel
-fan-out). That's one pair of eyes. When ocr is available, the
-wrapper adds a **second pair** — an independent LLM tuned for
-code review — and the two reviews are merged into the same
-`code-review.md` file. Soft-optional: if ocr isn't installed or
-configured, RD proceeds with the LLM-only review and the slice
-ships without the second opinion.
-
-## Install
-
-`@alibaba-group/open-code-review` is an **`optionalDependency`** of
-peaks-loop 2.0.3+ (was a required `dependency` in 2.0.1/2.0.2; reverted
-because the postinstall downloads a Go binary via HTTPS, which fails in
-restricted/proxied environments and would otherwise abort
-`npm i -g peaks-loop`). peaks-loop does NOT auto-install it. To enable
-the second-opinion review:
-
-```bash
-npm i -g @alibaba-group/open-code-review
-```
-
-(Under pnpm you also need `pnpm approve-builds @alibaba-group/open-code-review`
-so the binary download script can run.) Verify with:
-
-```bash
-peaks code-review detect-ocr --json
-```
-
-Five possible states:
-
-| state | Meaning | Recovery |
-|---|---|---|
-| `ready` | Installed + binary downloaded + peaks-loop's `peaksConfig.ocr.llm` valid | Nothing — `run-ocr` will work. |
-| `package-missing` | npm dep not installed (peaks-loop 2.0.3+ ships with ocr as an `optionalDependency`, so the common cause is the user has not installed it yet, or it was removed from node_modules) | `npm i -g @alibaba-group/open-code-review` (peaks-loop no longer auto-installs it; under pnpm also run `pnpm approve-builds @alibaba-group/open-code-review`) |
-| `binary-missing` | npm dep present but Go binary did not download | `pnpm approve-builds @alibaba-group/open-code-review`, OR run `node node_modules/@alibaba-group/open-code-review/scripts/install.js`, OR manually fetch from https://github.com/alibaba/open-code-review/releases and place the binary at the path shown in `nextActions[2]`. |
-| `config-missing` | binary present but `peaksConfig.ocr.llm` is empty or partial | See "Configure" below. |
-| `detection-failed` | Unexpected error during detection | Inspect stderr; re-run probe. |
-
-## Configure (one-time, per user) — peaks-loop does NOT auto-configure
-
-The LLM endpoint config is **user-maintained inside peaks-loop's own
-config** at `~/.peaks/config.json` under the `ocr.llm` key. The user
-is the only party that touches their LLM token / URL / model. peaks-loop
-never auto-writes the config and never writes `~/.opencodereview/config.json`.
-
-```bash
-# 1) Print the JSON snippet to paste (read-only, no side effects):
-peaks code-review config-template --json
-
-# 2) Paste the snippet into ~/.peaks/config.json under "ocr.llm",
-#    replace <your-api-key> with your real key. Alternatively,
-#    set keys one at a time:
-peaks config set --key ocr.llm.url --value 'https://api.example.com/v1/messages'
-peaks config set --key ocr.llm.authToken --value '<your-key>'
-peaks config set --key ocr.llm.model --value 'claude-3-5-sonnet-latest'
-peaks config set --key ocr.llm.useAnthropic --value 'true'
-peaks config set --key ocr.llm.authHeader --value 'x-api-key'
-
-# 3) Verify readiness (peaks-rd also runs this automatically):
-peaks code-review detect-ocr --json
-```
-
-### Field map: `peaksConfig.ocr.llm` ↔ ocr subprocess env vars
-
-peaks-rd calls ocr with the `peaksConfig.ocr.llm` values **injected as
-env vars** (ocr's highest-priority config path). The mapping is:
-
-| `peaksConfig.ocr.llm.*` | Spawn env var | Notes |
-|---|---|---|
-| `url` | `OCR_LLM_URL` | HTTPS endpoint, no embedded credentials |
-| `authToken` | `OCR_LLM_TOKEN` | Sensitive — stored only in the user-layer `~/.peaks/config.json`; `peaks config get` redacts this field |
-| `model` | `OCR_LLM_MODEL` | e.g. `claude-3-5-sonnet-latest` |
-| `useAnthropic` | `OCR_USE_ANTHROPIC` | Boolean; serialised as `"true"` / `"false"` |
-| `authHeader` | `OCR_LLM_AUTH_HEADER` | One of `authorization` (default Bearer), `x-api-key` (for `sk-ant-*` keys), or `bearer` |
-
-The `~/.opencodereview/config.json` file the user might have set up
-for 2.0.0 is no longer consulted by peaks-loop. The user may delete it
-at their discretion — the ocr subprocess ignores the file when peaks-
-cli's env vars are present (and the env-var surface is highest priority).
-
-### Required vs optional fields
-
-The minimum for `state == "ready"` is the **url + authToken + model**
-triple. `useAnthropic` and `authHeader` are optional; `authHeader`
-defaults to `authorization` (Bearer) inside the ocr subprocess, but
-`sk-ant-*` keys require `authHeader: "x-api-key"`.
-
-When the user has not yet populated the config, `detect-ocr` returns
-`state: "config-missing"` with `missingKeys: ["ocr.llm.url",
-"ocr.llm.authToken", "ocr.llm.model"]` and a templated
-`nextActions[1]` payload that includes the JSON snippet to paste.
-
-## Use from peaks-rd (LLM workflow)
-
-In Gate B3 (code review evidence), before writing
-`.peaks/_runtime/<sid>/rd/code-review.md`, the code-reviewer
-sub-agent runs:
-
-```bash
-# 1. Detect
-peaks code-review detect-ocr --json
-# 2. If state == "ready", run the review
-peaks code-review run-ocr --json --project . --from origin/main --to HEAD
-```
-
-The `run-ocr` envelope is:
-
-```jsonc
-{
-  "ok": true,
-  "command": "code-review.run-ocr",
-  "data": {
-    "spawned": true,
-    "state": "ready",
-    "exitCode": 0,
-    "stdout": "...",
-    "stderr": "",
-    "durationMs": 12345,
-    "parsed": {
-      "findings": [
-        { "file": "src/foo.ts", "line": 42, "severity": "minor", "message": "..." }
-      ]
-    },
-    "warnings": [],
-    "nextActions": []
-  },
-  ...
-}
-```
-
-Merge `data.parsed.findings` into `code-review.md` under
-`## Second opinion (ocr)`. Cite each finding by file + line.
-Reconcile disagreements with the LLM-only review explicitly
-(don't silently drop one source).
-
-## Soft-fail policy
-
-`peaks code-review run-ocr` **never** sets a non-zero exit code,
-even when ocr is not ready or the subprocess fails. The envelope
-`ok` field carries the success signal; the caller (peaks-rd) is
-expected to pattern-match on `data.state` and proceed without the
-second opinion if needed. This matches the ECC 64-agents
-soft-fail policy and the peaks-loop "minimal user operation"
-tenet — missing ocr should never block a slice.
-
-## Security
-
-- ocr sends your changed files to whatever LLM endpoint you
-  configure. Treat this the same as any external code-review
-  tool you opt into: don't point it at a free public endpoint
-  for proprietary code; use a vendor / self-hosted endpoint with
-  appropriate data controls.
-- peaks-loop does NOT auto-configure ocr. Your `ocr.llm.authToken`
-  is yours. Rotate as needed. The token is stored only in the
-  user-layer `~/.peaks/config.json` (project layer rejects writes
-  to any key matching `isSensitiveConfigPath`), and
-  `peaks config get` redacts it as `***`.
-- peaks-loop's wrapper records ocr's `stdout` verbatim in the
-  envelope (and in `code-review.md` when peaks-rd merges
-  findings). Don't put secrets in your code being reviewed.
-- The `peaks code-review config-template` snippet embeds the
-  placeholder string `<your-api-key>`; the user is expected to
-  replace it before pasting.
-
-## Failure modes (real)
-
-These are the actual failure modes the wrapper has been
-dogfooded against:
-
-1. **Network blocked from GitHub Releases** during postinstall →
-   `binary-missing`. peaks-loop still runs cleanly because ocr
-   is detected as not-ready; user manually fetches the binary
-   and places it at `nextActions[2]`'s path.
-2. **pnpm-installed peaks-loop** → ocr postinstall blocked by
-   pnpm's safe-by-default policy → `binary-missing`. Recover
-   with `pnpm approve-builds @alibaba-group/open-code-review`.
-3. **No / partial LLM config** → `config-missing` with
-   `missingKeys` listing the unpopulated fields. Recover by
-   pasting the `peaks code-review config-template` output into
-   `~/.peaks/config.json` (or by `peaks config set` per-key).
-4. **Wrong key / wrong endpoint** → ocr subprocess exits non-zero;
-   wrapper soft-fails (`ok: false`, `warnings[0]` includes the
-   exit code, `stderr` carries ocr's own error message).
-5. **User 2.0.0 → 2.0.1 migration** — they configured
-   `~/.opencodereview/config.json` for 2.0.0; peaks-loop 2.0.1
-   no longer reads that file. They paste the same values into
-   `~/.peaks/config.json` under `ocr.llm` (peaks-loop handles the
-   camelCase conversion in the template).
-
-## See also
-
-- ocr upstream: https://github.com/alibaba/open-code-review
-- peaks-loop source: `src/services/code-review/ocr-service.ts`,
-  `src/cli/commands/code-review-commands.ts`
-- peaks-loop config schema: `src/services/config/config-types.ts`
-  (`OcrLlmConfig`, `OcrConfig`, `PeaksConfig.ocr?`)
-- ECC 64-agents soft-optional pattern (mirrored):
-  `src/services/agent/ecc-agent-service.ts`