Ingesting a repository
Run the full pipeline, track it as a background job, and re-ingest cheaply as your code changes.
Ingestion is the full cgr → chunk → describe → upsert pipeline, enqueued as a background job by POST /instances/pipeline. The call returns immediately with a job_id; poll GET /instances/jobs/{job_id} (or stream its /events SSE) for stage progress and the final result.
Recreate vs upsert
recreate: true drops and rebuilds the entire collection (all projects) before inserting — needed only once after a schema change. Day-to-day ingestion should use recreate: false, which upserts entities in place by deterministic UUID and only removes this project's stale entities.
recreate: true wipes all ingested projects from Weaviate, not just this one. The CLI prompts before doing it.Fail-loud descriptor policy
describe defaults to true. While it's true, the configured descriptor is checked before the job is created — if it's missing or unavailable the request fails immediately with 400 and no job is created. Set describe: false to opt out: the pre-flight is skipped and the pipeline runs without descriptions (the summary vector stays empty for this run).
Graph-only runs
POST /instances/graph (and dokkai graph) run only cgr — no chunking, no descriptions, no embedding, no Weaviate. Stages go straight cgr → done, producing the same canonical graph JSON the full pipeline does. Useful to inspect a repo's dependency graph without Ollama or Weaviate running at all.
Per-project job lock
Only one job — pipeline, refresh, graph-only or a routine — may run at a time for a given project. Submitting a second returns 409 another job is running for project '<project>' and creates no job.
Keeping the index fresh
Re-ingesting is cheap: deterministic UUIDs upsert unchanged entities in place, and descriptions come from the source-hash cache instead of a fresh LLM call. Leave dokkai watch running to re-ingest incrementally on every save — see CLI → watch.