docs: add root README mapping the El monorepo #83

2026-07-23T19:36:11Z

andre.almeida commented

2026-07-23 19:36:11 +00:00

What & why

There was no root-level documentation for this monorepo — eight subprojects (lang, engram, elp, epm, ide, ql, ui, arbor), each with its own manifest/spec, but nothing tying them together for someone landing on the repo cold. This adds a root README.md that does that.

It covers:

The pitch and thesis — what El is (self-hosting, compiles to C) and why it exists (graph-native runtime instead of a bolted-on DB driver), pulled from lang/spec/language.md's Overview and the four defining properties already documented there.
An architecture map — how lang (compiler/runtime) relates to engram (the graph memory substrate) and the tools/systems built on top (epm, ide, elp, ql, ui, arbor).
A per-subproject summary — one section per top-level dir, each pulled from that subproject's actual manifest.el description(s) and spec/*.md where one exists, not written from assumption. Includes lang's current implemented-vs-planned status, sourced directly from lang/spec/language.md's Implementation Status section (the repo's stated single source of truth for that).
Getting started — install via lang/install.sh, or build from source and verify the self-hosting round-trip, then compile+run lang/examples/hello.el.
Development workflow — the dev → stage → main promotion pattern and per-subproject .gitea/workflows/ CI, both visible in existing repo history, plus where specs and agent-guides (AGENTS.md) live.
Status — repo is internal/proprietary, no license yet; flagged explicitly rather than left ambiguous.

Depth is intentionally a map, not a duplicate of each subsystem's docs — */spec/*.md, */README.md, and lang/AGENTS.md remain the source of truth for their own areas; the root README links out to them rather than re-explaining them.

Known gaps (flagged, not blocking)

elp/ and arbor/ have no spec/*.md of their own yet, so those two sections are sourced from manifest.el descriptions only, thinner than the lang/engram/ql/ui sections that had a spec to draw from.
No LICENSE file exists — the Status section states proprietary/internal in prose; a formal LICENSE would be a separate follow-up if wanted.

Verification

Docs-only change, no build/runtime impact — git diff main...feat/AddingReadme --stat shows a single new file, 154 insertions, nothing else touched.
Every path and file linked from the README (lang/BOOTSTRAP.md, lang/AGENTS.md, lang/spec/language.md, lang/spec/codegen-js.md, engram/README.md, ql/spec/elql.md, ui/spec/framework.md, lang/install.sh, lang/examples/hello.el, lang/examples/hello-project/, lang/releases/) was confirmed to exist in the tree before linking.
Every subproject description was cross-checked against its manifest.el description field rather than paraphrased from memory.

## What & why There was no root-level documentation for this monorepo — eight subprojects (`lang`, `engram`, `elp`, `epm`, `ide`, `ql`, `ui`, `arbor`), each with its own manifest/spec, but nothing tying them together for someone landing on the repo cold. This adds a root `README.md` that does that. It covers: - **The pitch and thesis** — what El is (self-hosting, compiles to C) and why it exists (graph-native runtime instead of a bolted-on DB driver), pulled from `lang/spec/language.md`'s Overview and the four defining properties already documented there. - **An architecture map** — how `lang` (compiler/runtime) relates to `engram` (the graph memory substrate) and the tools/systems built on top (`epm`, `ide`, `elp`, `ql`, `ui`, `arbor`). - **A per-subproject summary** — one section per top-level dir, each pulled from that subproject's actual `manifest.el` description(s) and `spec/*.md` where one exists, not written from assumption. Includes `lang`'s current implemented-vs-planned status, sourced directly from `lang/spec/language.md`'s Implementation Status section (the repo's stated single source of truth for that). - **Getting started** — install via `lang/install.sh`, or build from source and verify the self-hosting round-trip, then compile+run `lang/examples/hello.el`. - **Development workflow** — the `dev → stage → main` promotion pattern and per-subproject `.gitea/workflows/` CI, both visible in existing repo history, plus where specs and agent-guides (`AGENTS.md`) live. - **Status** — repo is internal/proprietary, no license yet; flagged explicitly rather than left ambiguous. Depth is intentionally a *map*, not a duplicate of each subsystem's docs — `*/spec/*.md`, `*/README.md`, and `lang/AGENTS.md` remain the source of truth for their own areas; the root README links out to them rather than re-explaining them. ## Known gaps (flagged, not blocking) - `elp/` and `arbor/` have no `spec/*.md` of their own yet, so those two sections are sourced from `manifest.el` descriptions only, thinner than the `lang`/`engram`/`ql`/`ui` sections that had a spec to draw from. - No `LICENSE` file exists — the Status section states proprietary/internal in prose; a formal `LICENSE` would be a separate follow-up if wanted. ## Verification - Docs-only change, no build/runtime impact — `git diff main...feat/AddingReadme --stat` shows a single new file, 154 insertions, nothing else touched. - Every path and file linked from the README (`lang/BOOTSTRAP.md`, `lang/AGENTS.md`, `lang/spec/language.md`, `lang/spec/codegen-js.md`, `engram/README.md`, `ql/spec/elql.md`, `ui/spec/framework.md`, `lang/install.sh`, `lang/examples/hello.el`, `lang/examples/hello-project/`, `lang/releases/`) was confirmed to exist in the tree before linking. - Every subproject description was cross-checked against its `manifest.el` `description` field rather than paraphrased from memory.

andre.almeida changed target branch from main to dev

2026-07-23 19:37:50 +00:00

andre.almeida added 1 commit 2026-07-23 19:42:17 +00:00

Addind readme.md file to start documenting the repo

El SDK CI - dev / build-and-test (pull_request) Successful in 8m18s

Details

b97b644799

andre.almeida force-pushed feat/AddingReadme from 849d54d73b to b97b644799

2026-07-23 19:42:17 +00:00

Compare

will.anderson reviewed 2026-07-28 03:18:29 +00:00

will.anderson left a comment

Welcome, André! Great first contribution — and a genuinely hard doc to write well, because El is a big monorepo. You've mapped it clearly and, importantly, accurately. I cross-checked the structural and technical claims against dev.

What's genuinely strong

The architecture map matches reality. All eight subprojects exist on dev (lang, engram, elp, epm, ide, ql, ui, arbor). arbor's six components are exact (arbor-core/-parse/-diagram/-layout/-render/-cli). ui is exactly 15 vessels. The engram description checks out against its spec: sled backing, spreading-activation retrieval, the four Working/Episodic/Semantic/Procedural tiers, and "flat cosine scan until scale demands an HNSW layer." The historical languages you name in elp (Old Norse, Sanskrit, Sumerian, Coptic, Akkadian, Ge'ez) are all present. This is well-researched.
"Why El exists" nails the framing. Graph operations as runtime primitives on the same footing as string/list ops, "the database is not separate" — that's exactly how we describe it, and it's the thing a newcomer most needs to internalize. The four defining properties (self-hosting → C → graph-native → DHARMA identity) are crisp.
The self-hosting section is a highlight. "Source is the ground truth, not the binary," plus the actual diff elc-new.c elc-verify.c reproducibility check in Getting Started, is exactly right and the kind of thing that makes BOOTSTRAP.md less scary.

One real nit (worth a small fix)

"31 languages" vs. what's on disk. I count 29 distinct morphology-*.el modules in elp/src (akk, ang, ar, cop, de, egy, enm, es, fi, fr, fro, gez, goh, got, grc, he, hi, ja, la, non, peo, pi, ru, sa, sga, sux, sw, txb, uga). If the canonical count is genuinely 31 (some languages may ride a shared/default morphology, or the profile enumerates more than have modules yet), a pointer to where the full list is authoritative — language-profile.el? — would let the number defend itself. Otherwise it's worth reconciling to 29. Small, but the rest of the doc is precise enough that readers will trust this figure.

Smaller notes (optional)

The inline ui vessel enumeration lists ~14 by name and skips el-native (the 15th on dev). Your "~15 vessels" count is correct; just noting the prose list is one short if you want it exhaustive.
el_val_t (int64_t) reads fine as a characterization; no change needed.

Overall: looks good — minor fixes. Only the "31 languages" number is worth touching before merge; everything else is accurate and clearly written. Base is correctly dev for gitflow. Really solid first PR.

Welcome, André! Great first contribution — and a genuinely hard doc to write well, because El is a big monorepo. You've mapped it clearly and, importantly, *accurately*. I cross-checked the structural and technical claims against `dev`. **What's genuinely strong** - **The architecture map matches reality.** All eight subprojects exist on `dev` (`lang`, `engram`, `elp`, `epm`, `ide`, `ql`, `ui`, `arbor`). `arbor`'s six components are exact (`arbor-core/-parse/-diagram/-layout/-render/-cli`). `ui` is exactly 15 vessels. The `engram` description checks out against its spec: `sled` backing, spreading-activation retrieval, the four Working/Episodic/Semantic/Procedural tiers, and "flat cosine scan until scale demands an HNSW layer." The historical languages you name in `elp` (Old Norse, Sanskrit, Sumerian, Coptic, Akkadian, Ge'ez) are all present. This is well-researched. - **"Why El exists" nails the framing.** Graph operations as *runtime primitives* on the same footing as string/list ops, "the database is not separate" — that's exactly how we describe it, and it's the thing a newcomer most needs to internalize. The four defining properties (self-hosting → C → graph-native → DHARMA identity) are crisp. - **The self-hosting section is a highlight.** "Source is the ground truth, not the binary," plus the actual `diff elc-new.c elc-verify.c` reproducibility check in Getting Started, is exactly right and the kind of thing that makes BOOTSTRAP.md less scary. **One real nit (worth a small fix)** - **"31 languages" vs. what's on disk.** I count **29** distinct `morphology-*.el` modules in `elp/src` (`akk, ang, ar, cop, de, egy, enm, es, fi, fr, fro, gez, goh, got, grc, he, hi, ja, la, non, peo, pi, ru, sa, sga, sux, sw, txb, uga`). If the canonical count is genuinely 31 (some languages may ride a shared/default morphology, or the profile enumerates more than have modules yet), a pointer to where the full list is authoritative — `language-profile.el`? — would let the number defend itself. Otherwise it's worth reconciling to 29. Small, but the rest of the doc is precise enough that readers will trust this figure. **Smaller notes (optional)** - The inline `ui` vessel enumeration lists ~14 by name and skips `el-native` (the 15th on `dev`). Your "~15 vessels" count is correct; just noting the prose list is one short if you want it exhaustive. - `el_val_t (int64_t)` reads fine as a characterization; no change needed. **Overall: looks good — minor fixes.** Only the "31 languages" number is worth touching before merge; everything else is accurate and clearly written. Base is correctly `dev` for gitflow. Really solid first PR.

will.anderson merged commit 8347a2f1c0 into dev

2026-07-31 04:25:45 +00:00

will.anderson referenced this pull request

2026-08-03 15:38:15 +00:00

Sync main into dev (GitOps: keep dev current; main authoritative) #84

Sign in to join this conversation.

2 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: neuron-technologies/el#83