searchi/SKILLS.md

Searchi agent workflows

This repository guide does not automatically install a Codex skill or plugin. Read AGENTS.md, README.md, and docs/ROADMAP.md before working.

Resume and implement

Inspect Git status and recent commits, preserve local changes, and choose a concrete roadmap milestone with acceptance criteria. Read relevant code and tests first. Assign paths for authorized parallel work and coordinate shared APIs. Keep the production goal active until all required gates have recorded evidence.

Search and indexing

Preserve strict filters before candidate limits, exact identifier priority, real Google vectors, source locations, atomic semantic generation activation, and stale/deleted source suppression. Test updates, renames, deletion, restart, corrupt documents, extraction limits, and interrupted work. Never silently drop searchable content or hide slow first inputs behind warm percentiles.

Runtime and setup

Use tools/embeddinggemma2/model-manifest.json and its pinned runtime builder. Normal distribution builds and staging use auto, with GPU support and CPU fallback in the same runtime. Force SEARCHI_FORCE_CPU=1 for every Windows VM inference test; explicit CPU builds are internal test tools only. Production acceleration requires separate hardware evidence. Verify size/SHA-256, cache reuse, interrupted downloads, errors, and retries. Keep inference local. Never substitute MiniLM, simulated vectors, or hosted inference. Ship the worker with the app.

Desktop design

The desktop UI is primary. Use native typography, chrome, dialogs, shortcuts, light/dark themes, reduced motion, and high contrast. Keep search dominant and previews readable; setup status must be honest. Preserve selection, focus, and scroll when semantic results arrive. Brief transitions must not delay requests or block interaction. The selected direction is the first generated concept, with Raycast as a reference: compact search, result rows, and a passage preview. Generated mockups do not establish functional PDF navigation or visual QA.

Run checks

Use stable Rust and Node.js 24+. Before Windows VM tests or launch:

$env:SEARCHI_FORCE_CPU = '1'
$env:WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS = '--disable-gpu --disable-accelerated-video-decode'

From the repository root:

cargo fmt --all -- --check
cargo test --workspace --locked
cargo clippy --workspace --all-targets --locked -- -D warnings
cargo fmt --manifest-path apps/desktop/src-tauri/Cargo.toml -- --check
cargo test --manifest-path apps/desktop/src-tauri/Cargo.toml --locked

From apps/desktop:

npm ci
npm test
npm run format:check
npm run build

Real-model tests require verified assets and the native CPU worker. Set SEARCHI_GEMMA_MODEL_DIR and SEARCHI_GEMMA_WORKER, then run:

cargo test -p searchi-semantic --test gemma_cpu -- --ignored --nocapture

Incremental reuse/recovery additionally requires verified CPU FFmpeg helpers in SEARCHI_TEST_FFMPEG and SEARCHI_TEST_FFPROBE. Run the actual Google integration:

cargo test -p searchi-service --test incremental_google_cpu --test google_cpu --locked -- --ignored --nocapture --test-threads=1

Completed-group reuse must preserve actual vector bytes and remap current source citations. Do not substitute simulated vectors or treat zero encoder calls as a foreground latency benchmark. See docs/INCREMENTAL-SEMANTIC.md for remaining gates.

Record actual outputs, hardware, corpus size, background preparation, first-input latency and warm latency in the relevant validation report. Unexecuted platform checks stay open. Compilation alone is not UI interaction verification. Use the opt-in measured search APIs and docs/PERFORMANCE.md for granular traces. Keep basic and debug overhead separate; do not sum nested stages or parallel lanes, or label DOM updates as actual paint. Retain raw measurement samples.

Commit and hand off

Review staged diffs for secrets, model binaries, generated files, and unfinished parallel work. Use Karl as author with no agent co-author trailers. Push only when authorized. Karl's infrastructure uses selected Infisical injection; never print credentials or commit them. Leave changed paths, checks, blockers, and a concrete next task. Mark roadmap items complete only with recorded evidence.