Emacs

Summary
Detail
See also

Summary

GNU Emacs is the extensible, self-documenting text editor that serves as ORE Studio's primary authoring and build environment. All documentation is written in Org mode, Emacs's structured plain-text format, and all build targets that produce the website, manuals, skills, and settings are implemented as Emacs Lisp scripts run in batch mode via emacs -Q --script. The interactive developer console (ores.lisp) also lives inside Emacs, providing a card-based dashboard for every day-to-day operation. No part of the production system depends on Emacs; it is strictly a developer and documentation toolchain.

Detail

Overview of Emacs

GNU Emacs, first released in 1984, is a programmable text editor whose central design principle is self-documentation: every key binding, variable, and function can be inspected, modified, or replaced at runtime using Emacs Lisp. This makes it well-suited to a project whose documentation and tooling evolve together — a new convention can be enforced immediately by adding a short Lisp function, with no external build pipeline required. ORE Studio exploits two Emacs subsystems in particular: Org mode (structured text, tables, literate programming via Babel, HTML/PDF export) and org-roam (the knowledge graph and id-link resolution layer).

Our setup

Developers load ORE Studio into Emacs by evaluating ores-env.el, which reads the checkout-local .env file and exposes helper functions for finding the project root and per-preset paths. The remaining modules — ores-dashboard, ores-db, ores-shell, ores-babel, ores-prodigy, ores-capture, and ores-org-roam-export — are then loaded on demand or as part of the dashboard initialisation. The entry point for interactive use is M-x ores/dashboard.

The knowledge graph (all .org files under doc/) is kept as the org-roam database at .org-roam.db in the repo root. org-roam synchronises this database whenever a developer opens or saves a file; the database is the authoritative source for id-link resolution both in interactive Emacs sessions and during batch site builds.

Build targets

All Emacs-driven builds run emacs -Q --script against the scripts below. The -Q flag suppresses the user's personal init file so builds are reproducible across machines. The preferred way to invoke them is compass build --direct <target> (Emacs only, no cmake/vcpkg — works in light environments); each also exists as a CMake custom target (the target names in the table) that runs the same script in a full environment. (deploy_plan has no --direct path — it needs cmake/=tj3=.)

CMake target	Script	What it produces
`deploy_site`	`ores-build-site.el`	Full documentation website published to `build/output/site/OreStudio`; includes org → HTML export, org-roam-ui graph, and graph JSON.
`deploy_manual`	`ores-build-manual.el`	User manual PDF from `doc/manual/user_guide/user_manual.org` via LaTeX.
`deploy_skills`	`ores-build-skills.el`	Claude Code skills tangled from Org Babel blocks into `.claude/skills/`.
`deploy_settings`	`ores-build-settings.el`	Claude Code settings JSON tangled from `doc/llm/claude_code_settings.org` into `.claude/settings.json`.
`deploy_plan`	`ores-build-plan.el`	TaskJuggler project plan tangled and exported from the agile docs.

The site build is the most involved: it syncs the org-roam database, publishes every .org file recursively via ox-publish, copies the pre-built org-roam-ui static bundle from external/org-roam-ui, injects the site navigation header into the graph page, and exports the graph data as JSON from the SQLite database so org-roam-ui can visualise it statically.