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:

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

From the repository root:

```sh
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:

```sh
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:

```sh
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:

```sh
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.