neuron-technologies/el
3
0
Fork 0
Code Issues 1 Pull Requests 1 Actions Packages Projects Releases 5 Wiki Activity

docs: add root README mapping the El monorepo #83

Open
andre.almeida wants to merge 1 commits from feat/AddingReadme into dev
pull from: feat/AddingReadme
merge into: :dev
Conversation 0 Commits 1 Files Changed 1
+154
andre.almeida commented 2026-07-23 19:36:11 +00:00
Member
Copy Link
Copy Source

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
All checks were successful
El SDK CI - dev / build-and-test (pull_request) Successful in 8m18s
Details
You are not authorized to merge this pull request.
This pull request can be merged automatically.
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u origin feat/AddingReadme:feat/AddingReadme
git checkout feat/AddingReadme
Sign in to join this conversation.
Reviewers
No Reviewers
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
andre.almeida (Andre Almeida) tim.lingo (Tim Lingo) will.anderson (Will Anderson)
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: neuron-technologies/el#83
Delete Branch "feat/AddingReadme"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?