Github: https://github.com/deadhedd/nre

## Introduction

Markdown-based note systems such as Obsidian have a property that is often underappreciated: the notes are just files.

A vault is simply a directory of Markdown documents. There is no proprietary database required to read the notes, and the files remain ordinary text that can be opened, moved, or backed up using standard tools. The editor provides a convenient way to browse and write them, but the files themselves remain ordinary documents.

That simplicity invites automation.

If a Markdown file can be placed in the vault manually, it can also be generated automatically. Daily dashboards, reports, summaries, and data snapshots are natural candidates.

A common approach in Obsidian workflows is to use plugins such as Templater or Dataview.

These plugins are extremely useful for templating notes, querying data, and connecting information within an Obsidian vault. However, their execution lives inside the editor.

In practice, scripts run only while the editor process is running and are typically triggered by events such as opening the editor, creating a note, executing a command, or a plugin lifecycle event. Logging is often minimal, and execution history can be difficult to observe.

Eventually a simple realization emerges.

If the notes are just files, the automation does not need to live inside the editor at all.

The editor is a viewer. The runtime is somewhere else.

That realization led to **nre — the Note Runtime Executor**.

To understand why such a runtime is useful, it helps to examine the limitations of editor-based automation.

—

## The Problem

Markdown notes are easy to automate because they are just files.

However, much note automation in these environments runs inside the editor itself. As automation grows more ambitious, this introduces several limitations:

* Automation only runs while the editor process is running.

* Execution is difficult to observe or debug after the fact.

* Generated artifacts are treated like interactive documents rather than build outputs.

These constraints are manageable for small conveniences, but they become increasingly difficult to work around as automation grows.

—

## The Automation Illusion

Some note-taking tools advertise automation features, but much of what is called automation ends up being **interaction-triggered scripting**.

Scripts run while the editor is active and are typically tied to editor events. In an Obsidian workflow, they might execute when the application starts, when a note is created, or when a command is triggered from the command palette.

This works well for writing workflows but limits independent automation.

For example, it becomes difficult to rely on the system to:

* generate tomorrow’s daily note overnight

* pull data from an API early in the morning

* produce scheduled reports at predictable times

Automation exists, but only within the boundaries of an editor session.

For simple workflows this is acceptable. As systems grow more complex, the limitations become more apparent.

The reason lies in how editors are structured internally.

—

## The Coupling Problem

Editors can host automation, but when execution lives inside the editor it shares the editor’s lifecycle and environment.

When automation lives inside the editor, multiple responsibilities become intertwined. The same application renders content, manages UI state, executes scripts, resolves queries, and maintains plugin state.

Over time this makes execution harder to reason about.

Scripts can depend on the runtime state of the editor, such as which plugins are loaded or how the application was started. In tools like Obsidian, plugin code runs inside the same process responsible for the interface.

Debugging therefore depends on the internal state of the editor.

None of this is the fault of plugin authors. The difficulty comes from asking an editor to behave like a runtime.

One consequence becomes clear as automation grows: the lack of reliable observability.

—

## The Observability Problem

Even when editor-based automation works, there is rarely a durable runtime record.

Logging is often minimal or inconsistent. Errors may appear only as broken notes or incomplete output, and execution history can disappear when the session ends.

When something goes wrong it can be difficult to determine:

* whether the script executed

* what inputs were used

* what artifacts were written

* why execution failed

Without logs, development becomes guesswork.

When something breaks, developers are left inspecting the resulting notes and trying to infer what happened.

This makes automation harder to build and maintain. Problems that would normally be trivial to diagnose can turn into long debugging sessions simply because there is no reliable record of execution.

Automation works best when it can be observed. Without visibility, even simple systems become difficult to reason about.

At the same time, another conceptual issue appears as automation expands.

—

## Not All Notes Are Documents

Many notes are not documents. They are artifacts.

Examples include dashboards, summaries, financial snapshots, weather checks, API data pulls, and system reports. These notes are not written manually; they are generated outputs.

Artifacts have different requirements than documents. They benefit from:

* deterministic outputs generated the same way each time

* reproducible generation when results must be recreated

* structured runtime logs explaining how they were produced

* versioned history to track changes

Treating these artifacts as interactive documents inside an Obsidian vault introduces unnecessary instability.

A better mental model is to treat them as **build outputs**.

This does not replace the editor or its plugins. Writing, linking, and exploring notes remain editor tasks. nre focuses only on generating artifacts.

Once artifacts are understood this way, the architectural correction becomes clear.

—

## The Architectural Correction

Execution moves outside the editor. A runtime generates artifacts, while the editor renders them.

The architecture becomes:

cron
   ↓
nre
   ↓
job
   ↓
artifact
   ↓
markdown vault

Scheduling happens independently. Execution occurs in a controlled environment. Generated artifacts appear in the vault as ordinary files.

From the editor’s perspective, they simply exist.

In an Obsidian workflow, they appear the next time the editor opens.

—

## What Changes When Automation Is Real

Once execution is decoupled from the editor, several things become possible.

Automation begins to behave more like infrastructure:

* Jobs run on schedules without requiring the editor.

* Automation can execute on machines without the editor installed.

* Execution becomes observable through structured runtime logs.

* Artifacts become reproducible outputs rather than interactive state.

Schedules become explicit. Scripts become jobs. Jobs become observable. Artifacts become infrastructure.

nre is a small runtime designed to support this model.

—

## Introducing nre

**nre — the Note Runtime Executor —** provides a deterministic runtime for generating Markdown artifacts while keeping a narrow scope.

It does not schedule jobs, manage a GUI, or replace cron. Scheduling remains external: cron decides **when** jobs run, and nre defines **how** they run.

—

## What nre Provides

nre introduces capabilities that editor-based automation often lacks.

Each job execution produces:

* timestamped runtime logs

* structured severity levels

* explicit execution phases

* captured stdout and stderr

* recorded exit codes

Jobs declare the artifacts they generate, and those artifacts are written deterministically.

Failures leave clear evidence in the logs, while successful runs leave an inspectable trace. This makes automation easier to develop, debug, and reason about.

—

## Headless Operation

Once execution is separated from the editor, automation can run entirely on a headless server.

Jobs generate Markdown artifacts, commit them to a repository, and the vault synchronizes like any other directory.

From the user’s perspective, notes simply appear. When questions arise, the logs explain how they were produced.

—

## The Mental Model

Conceptually, nre behaves like `make` for notes.

Cron triggers execution, nre enforces runtime semantics, and the vault receives generated artifacts. Logs explain how those artifacts were produced.

This separation keeps each component simple while keeping the system predictable.

—

## The Result

With a proper runtime and structured logs, the system can produce deterministic daily notes, reproducible reports, observable dashboards, and Git-backed artifact history.

Automation runs without requiring the editor, and failures can be diagnosed through logs rather than guesswork.

The editor returns to its natural role: a viewer and writing tool for Markdown files.

Nothing more is required.