# Searchi development

Read README.md, SKILLS.md, and docs/ROADMAP.md before starting or resuming work.
For UI, assets, or public-facing copy, also read docs/BRAND.md. Use lowercase
searchi and the approved brand assets and palette consistently.
Inspect Git status and preserve existing changes. Do not claim production
readiness without completed release gates and recorded evidence.

- All tests in the Windows VM must use CPU only. Never enable GPU providers here.
- Production uses available GPU/hardware acceleration with reliable CPU fallback;
  the CPU-only rule is a VM testing constraint, not a product restriction.
- Keep the Rust engine independent of the desktop shell; CLI and UI share its API.
- Prefer established Rust crates and proven retrieval algorithms over custom
  implementations. Keep platform adapters small, bound allocations and queues,
  and measure performance before adding caches or changing ranking policies.
- Use bounded work, explicit errors, versioned storage, and offline defaults.
- Never substitute simulated embeddings for working semantic search.
- Production semantic search must use Google EmbeddingGemma 2 as in DigUp.
  MiniLM proof artifacts are historical experiments, not an accepted backend.
- The desktop UI is the primary product, including local model setup and semantic
  indexing/search. Keep a separate CLI-only build for headless Linux with no GUI dependencies.
- Desktop setup must work out of the box: ship the native worker, automatically
  download/verify missing Google assets, reuse cached assets, and expose progress/retry in the UI.
- Add meaningful tests for retrieval, persistence, and filesystem lifecycle changes.
- Keep docs/ROADMAP.md current. Unexecuted platform checks remain unchecked.
- Agents own assigned paths and must coordinate shared interface changes. Do not commit other agents' unfinished work.
- Prepare indexes and the real Google query session in the background. Retain
  warmed readers and keep keyword search usable during setup. Measure startup,
  actual first input, and warm p95 separately.
- UI should belong to each OS: native typography/chrome/dialogs, themes,
  keyboard access, reduced motion and high contrast. Brief transitions must not
  delay requests. Preserve selection/focus as progressive results arrive.
- Follow SKILLS.md for validation and handoffs. Leave actual checks, blockers,
  and concrete next tasks. Keep unexecuted OS and GPU checks explicitly open.
- Use karl as Git author with no agent co-author trailers. Keep credentials,
  model binaries, generated build assets, and local indexes out of Git.