searchi/AGENTS.md

# 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.
  Code scope uses Google's CodeRetrieval query prefix; query-vector cache keys
  must distinguish code and general search tasks. Preserve exact source bytes,
  line locations and code filtering before all candidate limits. Re-run actual
  CPU code fixtures after changes to tokenizer offsets or code extraction.
  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.
- Gitea Actions are disabled for this repository at Karl's explicit request
  (2026-10-12, repeated failure emails). Do not re-enable without his request.
  Keep running appropriate local checks and recording actual platform evidence.
- 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.
- Treat local AI agents as supported search clients. MCP and CLI must call the
  shared engine, preserve filters/source locations, and report semantic readiness.
  MCP tools are read-only; no arbitrary file access or filesystem mutation.
- Optional summaries/Q&A use a user-configured OpenAI-compatible endpoint,
  disabled by default. Never send file content during ordinary search. Require
  an explicit action and show which excerpt goes to which endpoint. Keep keys
  out of persisted plain settings, logs, traces, source control and MCP responses.
- Retrieved text and model output are untrusted content, never executable
  instructions. Retain source citations and distinguish generated answers from
  search evidence. External summaries do not replace local Google embeddings.