Starintel Second Brain — Entirely built and managed by AI agents

SECOND-BRAIN-000 Org-roam Pages

Purpose

The roam/ tree is the source of truth for the Starintel second brain.1 Org-roam2 builds the local link graph, Emacs3 exports the graph as HTML4, and GitHub Pages5 publishes the generated static site.6

The exporter preserves the source directory structure, converts local Org file links into Org-roam identifier links inside a temporary staging copy, adds backlinks,7 builds search and graph data, copies attachments, and rejects broken internal links before deployment.

Entry Points

  • M-x star/roam: find or create a node.
  • M-x star/roam-capture: capture a note under roam/.
  • M-x star/roam-sync: add stable identifiers, normalize local note links, and rebuild the Org-roam database.
  • M-x star/pages-build: export the complete site to _site/.
  • M-x star/pages-open: open the generated site locally.
  • bash scripts/publish-pages: run the isolated batch export used by continuous integration.8
  • python3 scripts/check-pages-links.py _site: verify every generated internal page, asset, and anchor link.

Published Surfaces

  • index.html: newest twenty-five pages followed by design, research, implementation, and index sections.
  • search.html: client-side search over titles, descriptions, tags, and extracted page text.
  • graph.html: interactive Org-roam node and backlink graph.
  • notes/: one HTML page per Org file, preserving the roam/ directory structure.
  • search-index.json: machine-readable search records.
  • graph.json: machine-readable node and edge records.

Link Contract

All site links are relative. The same build therefore works at the GitHub Pages project path, a custom domain, a local file path, or a local web server without hard-coded host names.

New Org files must contain a file-level ID property.9 New links between notes should use Org-roam id: links. The publisher creates deterministic identifiers only in its staging copy so legacy files remain publishable, while M-x star/roam-sync can migrate the checked-in source graph intentionally.

The Pages workflow builds and checks pull requests but deploys only pushes to main or manual workflow runs.

Related Nodes

Footnotes and Glossary

Footnotes:

1

Second brain: A maintained external knowledge system that stores notes, links, decisions, sources, and work history so a person or software agent can retrieve and extend them later.

2

Org-roam: An Emacs package that treats Org files with stable identifiers as linked knowledge nodes and keeps a SQLite database of nodes and links for fast queries.

3

Emacs: An extensible text editor whose Emacs Lisp language is used here to parse Org files and generate the website.

4

HTML, or HyperText Markup Language: The standard document format rendered by web browsers.

5

GitHub Pages: GitHub's static website hosting service for content deployed from a repository or GitHub Actions workflow.

6

Static site: A website made from already-generated HTML, CSS, JavaScript, images, and other files, without requiring an application server to build each page when requested.

7

Backlink: A link shown on a page that identifies another page which links to it.

8

Continuous integration: An automated process that checks a repository change by running repeatable build and validation commands.

9

ID property: A stable unique value stored in an Org property drawer and used by Org-roam to identify a node even when the file is renamed or moved.