evb-viewer

Imported from evb0110/evb-viewer (AGENTS.md). Install upstream with npx skills add evb0110/evb-viewer. Copyright stays with the author.

EVB Viewer agent rules

Start with ARCHITECTURE.md for the engineering map. Shared personal preferences live in ~/AGENTS.md.

Design and checks

• Prefer deletion and reuse. Give state and lifecycles one owner, derive other views, and validate at trust boundaries using existing contracts. Extend shared mechanisms instead of adding feature-local copies.
• New layers should replace old ones. See the design charter and ADRs when changing architecture.
• A change a user could see or feel follows fix evidence: reproduce it in a hidden real-app session with real input before fixing, show the same script failing before and passing after, and otherwise report "mitigation applied, not confirmed". This applies to delegated workers too; never forbid a worker from launching the hidden app for such a change. Expected behavior comes from the behavior contract, not from the implementation.
• Test what a user perceives: rendered text, real layout, pixels, saved bytes. One adequate real-app proof per scenario is enough. A geometry, lifecycle or interaction fix cannot close on a mock-level test alone, and do not add tests that assert private call sequences. Releases use run-all-gates; independent review is useful only when it adds coverage.
• New check infrastructure or flake tolerance requires an explicit user request and the commit trailer Adds-Checks: <the words that asked for it>. One focused real-app regression test in an existing lane for a user-facing fix is pre-authorized with Adds-Checks: real-app regression for a user-facing fix; new runners, jobs, lanes or monitors are not. Editing or deleting existing checks needs no trailer. After a push, wait for the required verdict only with ci-wait -w CI; the extended tier reports separately and a newer push supersedes it, so plain ci-wait would wait half an hour and report that cancellation as a failure. Before diagnosing a red main, run node scripts/ci/ci-health.mjs --sha <sha>; a failure it marks inherited already has an owner. Before changing a flaky check, run node scripts/ci/ci-health.mjs.
• At most two viewer-core changes are active at once and they integrate one at a time, as fix evidence describes. Work comes from observed behavior: owner-blocking failures, recurring defect families, then failures from ordinary tasks on varied documents. Do not start a static audit program unless the owner asks for one.

OCR and UI

• Prioritize OCR quality and robustness. Use the pinned tesseract-ocr/tessdata_best models and keep their registry in sync.
• Use tokens from app/assets/css/main.css, localize UI strings with t() in English and Russian, and register icons in clientBundle.icons in nuxt.config.ts.
• Before changing annotation serialization or note windows, read freetext persistence.

Operations

• For agent UI work and video evidence, use recorded automation and start a task-owned recorded session. The same CLI works for every model provider.

• Before any Electron launch, follow hidden automation and its shared runner. Resolve the specific dev session over CDP using session lifecycle; a generic Electron app name or bundle ID can target another task's app.

• Before cleanup, read workspace hygiene. Preserve active worktrees, .devkit data, and Rust targets.

• Issues and specs live in GitHub. Use the issue tracker and triage labels.

• For Windows tests, follow UTM tests and setup and repair. Use pnpm windows:test*; never target the personal VM named Windows or record its UUID or bundle path.

• For an ambiguous Sentry check, start with Sentry agent check, which defines the read-only default.