Getting Started

New here? Start from what you’re trying to do — each goal points to the tool that calibrates it.

Run Nexus in five minutes

Docker is the only thing you need installed. Everything else runs inside the compose stack.

git clone https://github.com/LivingLikeKrillin/khala.git
cd khala
cp nexus/.env.example nexus/.env     # then set ANTHROPIC_API_KEY for narrated answers
task up

No Task? task up is three commands — run them from nexus/:

cd nexus
docker compose up -d --wait                                  # containers + model auto-pull
docker compose exec -T nexus-app python -m scripts.migrate   # ← skip this and the source console / document management break

The first boot builds the image, which compiles mecab-ko from source — budget 10–20 minutes. Later runs start in seconds. The embedding model (nomic-embed-text, ~274 MB) is pulled automatically on first boot.

Now index something. An empty corpus answers every question with “not found”, so this step is not optional:

cd nexus
docker compose exec nexus-app nexus ingest ./docs   # index the shipped design docs

Open http://localhost:8000/ and ask a question. Answers cite the chunks they came from; if the corpus doesn’t contain the answer, Nexus says so instead of guessing.

Without ANTHROPIC_API_KEY you still get the retrieved evidence — just not a narrated answer.

To stop: task down. To update after git pull: task update (rebuilds and runs DB migrations).

Routing by Engineering Goal

Engineering Objective	Recommended Tool	Verification Mechanism
Query codebase and domain specs with citable grounding	Nexus / Archon	Hybrid retrieval (BM25 + Vector) & static invariant checking
Ground PR impact analysis & incident triage in live telemetry	Observer	Nexus knowledge substrate + OpenTelemetry trace correlation
Establish accountable architectural review gates	Arbiter	Pre-implementation specification review & cryptographic content hashing
Measure empirical fault-detection capabilities of test suites	Probe	Mutation testing harness via AST manipulation
Quantify organizational comprehension deficit against codebase	Adept	Vouch coverage measurement over knowledge corpus

5-minute tour

What is Khala? → Philosophy → Ecosystem

Prerequisites

Common: git, a recent runtime.
Nexus: Docker (Postgres etc. run inside the compose stack — no separate install). Observer: Node ≥20. Arbiter / Probe / Adept: Python (Probe needs cosmic-ray).