← Documentation hub

First 15 minutes with Knode

Use this after KNODE-INSTALL.md. Goal: corpus → API key → index → first answer.

1. Create or locate corpus.jsonl

Knode does not ship reading data. You need a JSONL file: one JSON object per line (Kindle highlight rows). Typical path:

  1. Capture from Kindle Notebook with the WebView spike: spike/webview-notebook/README.md.
  2. Dedupe (if needed) → run parse_dump and validate_corpus from mvp/: KNODE-MVP-GUIDE.md §4.

In the app: Help → How do I get corpus.jsonl? repeats this pipeline with commands.

2. Open Knode and use Setup · Corpus & index

  1. In the left nav, choose Setup · Corpus & index (gear).
  2. Highlight file → Browse… → select your corpus.jsonl.
  3. AI agent API key → paste a Google AI Studio key (this MVP uses Gemini only).
    Optional: Remember API key (stored with Windows DPAPI under %LocalAppData%\Knode\).
  4. Click Build index.
    - First time on a large library may take several minutes (embedding batches).
    - If you already had an index for the same file hash and model, it may load without re-embedding.

Wait until status shows ready (e.g. loaded or built with highlight count).

3. Ask a question

  1. Switch the left nav to Ask.
  2. Type a question (or use a Try a prompt chip).
  3. Click Ask.
  4. Read the Answer; expand Sources to see retrieved passages and match strength.

4. If something fails

Symptom What to try
Ask disabled Finish Setup: valid corpus path, key present, Build index succeeded.
Blank Answer / Sources panes Install WebView2 Runtime; restart Knode.
429 / rate limit during index Increase Knode:EmbeddingBatchDelayMs in appsettings.json next to Knode.exe (see dotnet/Knode/appsettings.json in source).
503 / “high demand” / UNAVAILABLE on Ask or Build index Usually temporary on Google’s side. The app retries (up to several times with backoff). Wait and try Ask again; try off-peak hours; confirm quota in Google AI Studio. You can set ChatModel to another Gemini model in appsettings.json if one tier is overloaded.
Wrong or empty retrieval Re-run validate_corpus on the JSONL; check Setup path matches the file you indexed.

More: KNODE-MVP-GUIDE.md (product and architecture context), spike/webview-notebook/QUALITY-CHECKLIST.md (capture quality).