Parcours — the guided path
Guided onboarding
The documentation is a map, organized by system. This page is the walk: the same pages, in the order a newcomer should live them. Follow it top to bottom. You go from an empty machine to a running hub, a fused entity, a métier chat that cites its sources, and a workflow that flags what stopped moving.
Run every command from the repository root unless a page says otherwise. Half of all mysterious failures are a wrong working directory.
You do not have that repository yet — step 2 below is where you get it. If you want it now:
git clone https://github.com/icreated/lumnik-open.git && cd lumnik-open
The three half-days at a glance
Deploy the hub, meet lm, run the WOW, and prove that ingestion stayed read-only and lost nothing.
Six steps, ≈ 3 h
Understand entities, honesty guards, scopes, models, and the TUI an integrator operates from.
Six steps, 3 h
Move from a mirror of the source to views, processes, workflows, inbox decisions, and the métier PWA.
Six steps, ≈ 3 h 15
Half-day 1 — defrost reading
Goal of the day: legacy data flows into the hub, read-only, and you can prove nothing was lost.
Read the Home page. It tells you what lumnik is (a read-only defrost of legacy systems) and, just as important, what it is not (not a migration, not a BI project).
You know it landed when: you can explain why lumnik is neither a migration nor a BI project.
Follow Deploy lumnik, self-host path: one command, deploy/selfhost/up.sh. It generates all secrets into a local .env — your credentials live there, including HUBADMIN_PASSWORD.
You know it worked when: the script reports the stack healthy and prints where the hub answers.
lmThe 60-second Quickstart builds the lm binary, points it at your hub, and logs you in — then puts a first file into the hub with one command.
You know it worked when: lm login succeeds and lm connector list answers — an authenticated round trip to your own hub.
$ lm connector list
NAME TYPE TENANT SCHED WINDOW STATUS LAST RUN
customers csv-file 1 Completed 2026-09-05 05:38
The heart of the first half-day. Read The WOW, step by step, then replay it yourself with The WOW, hands-on: a SOAP Siebel and a CSV fused into one canonical Customer, asked in natural language.
You know it worked when: you ask a question in French and the answer cites its sources.
Now that you have seen one run, read Connectors overview and the manifest you just used, CSV & files. Every other source type follows the same grammar — the full list is on the shelf below.
You know it landed when: you can explain the relationship between manifest, endpoint, and ingestion report.
Read Seeing what was ingested, skipped, and quarantined.
You know it worked when: on your own run, lm run get shows the arithmetic holding — IN = OUT + SKIPPED — and DEAD-LETTERS never exceeds SKIPPED: every row you read is accounted for, dropped or not.
$ lm run get f0466804
ID CONNECTOR ENDPOINT STATUS IN OUT SKIPPED DEAD-LETTERS STARTED ENDED
f0466804 orders default Completed 10 8 2 2 2026-09-05 05:38 2026-09-05 05:38
⚠ 2 rows quarantined — see: lm dlq list --run f0466804-0824-4eb4-8aa2-54e263dccafe
Half-day 2 — defrost reasoning
Goal of the day: the ingested data answers questions — sources shown, and only to the people entitled to ask.
Read Entities — fuse and inspect the Customer entity you applied during the WOW.
You know it worked when: you can find the _conflicts ledger and explain why a row is in it.
Read Ask honesty — the five guards. This page is lumnik's spine: an abstention is a feature, a confident wrong answer is the cardinal sin.
You know it worked when: you can name the guard that stops a hallucinated table name.
Read Scopes: a scope is declared on the connector (metadata.scopes) and granted as a Keycloak role. Zero scope roles = tenant-wide; one or more = bound.
You know it worked when: a scope-bound user gets 403 scope not granted outside their métier — and sees answers inside it.
Read Models & providers to know which LLM answers you, and how to swap it (Ollama local or a remote provider).
You know it worked when: you know whether your install answers from Ollama or a remote provider.
Skim the CLI & TUI reference, then open the TUI with lm ui and redo yesterday's WOW checks without leaving it.
You know it worked when: you can find any connector run and its report using only the TUI.
Read Roles & permissions and skim RLS & database roles: tenant isolation is enforced by the database itself, not by application code being careful.
You know it landed when: you can explain why isolation survives even a buggy query.
Half-day 3 — defrost time and the apps
Goal of the day: the hub stops being a mirror and starts finding things — and each métier gets a surface.
Read Views and apply the WOW's saved view.
You know it worked when: GET /api/views lists it and a scoped user can render it.
Read Processes: declarative reactions to data.row.changed, always refusable, never writing to the source.
You know it landed when: you can say what emits the event and what may refuse the action.
Read Workflows. This is the third defrost axis: the source shows current state; lumnik, ingesting repeatedly, reconstructs time — and a declared lifecycle plus a dormancy threshold turns silence into an alert.
You know it worked when: the métier chat answers a lifecycle question from your declared graph, not from imagination.
Read Inbox: where decision.* events (including decision.dormant.<workflow>) wait for a human, and the ack gesture that closes the loop.
You know it landed when: you can distinguish the emitted event from the human acknowledgement.
Read The métier PWA and open https://<your-host>/app/ on a phone: cards on a phone, a table on a tablet, the same scope rules as everywhere else. A phone cannot reach your laptop's localhost — the TLS façade on the deploy page is what gives both devices one host and one token issuer.
You know it worked when: you see the same scope boundary on the phone and on the desktop.
Read Backup & restore and Upgrade — the two pages you must have practiced before the day you need them.
You know it worked when: you have run one backup and know where it landed.
If you get stuck
Lessons from the first strangers who walked this path — each of these cost someone an hour:
- Wrong directory. Commands assume the repository root. When a relative path fails, check where you are before checking anything else.
- The first minute is not an outage. Right after the stack starts, the hub can briefly
answer
401or refuse connections. Wait a minute and retry before diagnosing. - The ghost binary. After rebuilding
lm, runlm version. If it prints an old build, your PATH serves a stale copy — prefer a symlink to your build overcp. - Credentials. Everything is generated at install time into the
.envnext toup.sh. If a login page surprises you, the answer is in that file. - Ollama pulls one model at a time. One
ollama pull <model>per line, and make sureollama serveisn't already running before starting it again.
If a step of this parcours doesn't match what you experience, that gap is a bug in the documentation — please report it. The stumbles of the first walkers are folded back into this page.
The reference shelf
Everything not on the walk above, so nothing in the documentation is orphaned. Come back here when the need arises — not before.
More source types — same manifest grammar as CSV: JDBC · REST · GraphQL and SOAP — request shapes on the REST engine · Kafka inbound · Transform at ingestion
Integrations & API — HTTP API for ask · Admin API
Enterprise identity — Bring your own IdP · SCIM deprovisioning
Day-2 operations — Observability · Rate limits · Sizing & load tests
Deploying at scale — the cloud edition (commercial) ships a Kubernetes/Helm path; not part of this repository.